Teradata Package for Python Function Reference | 20.00 - BinaryMatrixOp - 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
 
 
BinaryMatrixOp

 
Functions
       
BinaryMatrixOp(data1=None, data1_filter_expr=None, data2=None, data2_filter_expr=None, math_op=None, input_fmt_input_mode=None, output_fmt_index_style='NUMERICAL_SEQUENCE', **generic_arguments)
DESCRIPTION:
    The BinaryMatrixOp() function performs a point-wise mathematical
    operation on two matrices with an equal number of wavelets and for
    which corresponding wavelets have an equal number of data points.
 
    A point-wise operation signifies that a mathematical operation is
    performed on one sample point at a time. Allowed mathematical
    operations are addition, subtraction, multiplication and division.
    
    The BinaryMatrixOp() function takes two equally sized logical-runtime
    matrices as input - the first matrix referenced in the function call
    ("data1") is a primary matrix, whereas the second matrix referenced
    ("data2") is a secondary matrix. The significance of being a primary
    or secondary matrix in each of the allowed mathematical operation is as
    follows:
        * SUB: The secondary matrix is subtracted from the primary matrix.
        * ADD: The secondary matrix is added to the primary matrix.
        * MUL: The primary matrix is multiplied by the secondary matrix.
        * DIV: The primary matrix is divided by the secondary matrix.
    
    The result matrix produced by the BinaryMatrixOp() function is of 
    the same size, 'N * M', as of its inputs and inherits the TDMatrix
    identifier (id), from the primary matrix.
    
    The BinaryMatrixOp() function can be configured to operate in one
    of three input modes - ONE2ONE, MANY2ONE, and MATCH. These modes
    determine the number of primary matrices and number of secondary
    matrices involved in the operation, as well as determining how the
    primary and secondary matrix will be matched together.
 
    The common uses of BinaryMatrixOp() function are:
        * Addition:       Restore trends to a time matrix before using the
                          model for forecasting.
        * Subtraction:    Subtract trends from a time matrix to create a
                          model from it.
        * Multiplication: Apply a low pass, band pass, or high pass
                          filter to a time matrix.
        * Division:       Divide the primary matrix by the secondary matrix.
 
 
PARAMETERS:
    data1:
        Required Argument.
        Specifies the primary matrix in the mathematical operation.
        Note:
            The matrices specified in "data1" and "data2" must have
            the same dimensions.
        Types: TDMatrix
 
    data1_filter_expr:
        Optional Argument.
        Specifies the filter expression for "data1".
        Types: ColumnExpression
 
    data2:
        Required Argument.
        Specifies the secondary matrix in the mathematical operation.
        Note:
            The matrices specified in "data1" and "data2" must have
            the same dimensions.
        Types: TDMatrix
 
    data2_filter_expr:
        Optional Argument.
        Specifies the filter expression for "data2".
        Types: ColumnExpression
 
    math_op:
        Required Argument.
        Specifies the mathematical operation to be performed
        between "data1" and "data2".
        Permitted Values:
            * SUB: The secondary matrix is subtracted from the primary matrix.
                   This subtracts trends from a time matrix to create a model
                   from it.
            * ADD: The secondary matrix is added to the primary matrix.
                   This restores trends to a time matrix before using the model
                   for forecasting.
            * MUL: The primary matrix is multiplied by the secondary matrix.
                   This applies a low pass, band pass, or high pass filter to
                   a time matrix.
            * DIV: The primary matrix is divided by the secondary matrix.
                   This divides the primary matrix by the secondary matrix.
        Types: str
 
    input_fmt_input_mode:
        Required Argument.
        Specifies the input mode supported by the function.
        Permitted Values:
            * ONE2ONE: Both the primary and secondary matrix
                       specifications contain a matrix name
                       which identifies each of the two matrices
                       in the function.
            * MANY2ONE: The MANY specification is the primary matrix
                        declaration. The secondary matrix specification
                        contains a matrix name that identifies the
                        single secondary matrix.
            * MATCH: Both matrices are defined by their respective matrix id.
        Types: str
 
    output_fmt_index_style:
        Optional Argument.
        Specifies the index style of the output format.
        Default Value: NUMERICAL_SEQUENCE
        Permitted Values: NUMERICAL_SEQUENCE, FLOW_THROUGH
        Types: str
 
    **generic_arguments:
        Specifies the generic keyword arguments of UAF functions.
        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.
                Note that, when UAF function is executed, an 
                analytic result table (ART) is created.
                Default Value: False
                Types: bool
 
            volatile:
                Optional Argument.
                Specifies whether to put the results of the
                function in a volatile ART or not. When set to
                True, results are stored in a volatile ART,
                otherwise not.
                Default Value: False
                Types: bool
 
            output_table_name:
                Optional Argument.
                Specifies the name of the table to store results. 
                If not specified, a unique table name is internally 
                generated.
                Types: str
 
            output_db_name:
                Optional Argument.
                Specifies the name of the database to create output 
                table into. If not specified, table is created into 
                database specified by the user at the time of context 
                creation or configuration parameter. Argument is ignored,
                if "output_table_name" is not specified.
                Types: str
 
 
RETURNS:
    Instance of BinaryMatrixOp.
    Output teradataml DataFrames can be accessed using attribute 
    references, such as BinaryMatrixOp_obj.<attribute_name>.
    Output teradataml DataFrame attribute name is:
        1. result
 
 
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.
 
    # Check the list of available UAF analytic functions.
    display_analytic_functions(type="UAF")
 
    # Load the example data.
    load_example_data("uaf", ["binary_matrix_complex_left", "binary_matrix_complex_right"])
    load_example_data("uaf", ["binary_matrix_real_left", "binary_matrix_real_right"])
 
    # Create teradataml DataFrame objects.
    data1 = DataFrame.from_table("binary_matrix_complex_left")
    data2 = DataFrame.from_table("binary_matrix_complex_right")
    data3 = DataFrame.from_table("binary_matrix_real_left")
    data4 = DataFrame.from_table("binary_matrix_real_right")
 
    # Create teradataml TDMatrix objects.
    binary_matrix_complex_left = TDMatrix(data=data1,
                                          id="id",
                                          row_index="seq",
                                          column_index="tick",
                                          row_index_style="SEQUENCE",
                                          column_index_style="SEQUENCE",
                                          payload_field=["real_val", "imaginary_val"],
                                          payload_content="COMPLEX")
 
    binary_matrix_complex_right = TDMatrix(data=data2,
                                           id="id",
                                           row_index="seq",
                                           column_index="tick",
                                           row_index_style="SEQUENCE",
                                           column_index_style="SEQUENCE",
                                           payload_field=["real_val", "imaginary_val"],
                                           payload_content="COMPLEX")
 
    # Example 1 : Perform addition operation in MANY2ONE mode between
    #             two matrices holding COMPLEX payload.
    uaf_out_1 = BinaryMatrixOp(data1=binary_matrix_complex_left,
                               data2=binary_matrix_complex_right,
                               data2_filter_expr=binary_matrix_complex_right.id==1,
                               math_op="ADD",
                               input_fmt_input_mode="MANY2ONE")
 
    # Print the result DataFrame.
    print(uaf_out_1.result)
 
    # Example 2 : Perform multiplication operation in MATCH mode between
    #             two matrices holding REAL payload.
    # Create teradataml TDMatrix objects.
    binary_matrix_real_left = TDMatrix(data=data3,
                                       id="id",
                                       row_index="seq",
                                       column_index="tick",
                                       row_index_style="SEQUENCE",
                                       column_index_style="SEQUENCE",
                                       payload_field="a",
                                       payload_content="REAL")
 
    binary_matrix_real_right = TDMatrix(data=data4,
                                        id="id",
                                        row_index="seq",
                                        column_index="tick",
                                        row_index_style="SEQUENCE",
                                        column_index_style="SEQUENCE",
                                        payload_field="b",
                                        payload_content="REAL")
 
    uaf_out_2 = BinaryMatrixOp(data1=binary_matrix_real_left,
                               data2=binary_matrix_real_right,
                               math_op="MUL",
                               input_fmt_input_mode="MATCH")
 
    # Print the result DataFrame.
    print(uaf_out_2.result)