teradataml.dataframe.dataframe.DataFrame.map_partition = map_partition(self, user_function, exec_mode='IN-DB', chunk_size=1000, num_rows=1000, data_partition_column=None, data_hash_column=None, **kwargs)

        DESCRIPTION:
            Function to apply a user defined function to a group or partition of rows
            in the teradataml DataFrame, leveraging Vantage's Script Table Operator.
 
        PARAMETERS:
            user_function:
                Required Argument.
                Specifies the user defined function to apply to each group or partition of
                rows in the teradataml DataFrame.
                Types: function or functools.partial
 
                Notes:
                    * This can be either a lambda function, a regular python
                      function, or an object of functools.partial.
                    * The first argument (positional) to the user defined
                      function must be an iterator on the partition of rows
                      from the teradataml DataFrame represented as a pandas
                      DataFrame to which it is to be applied.
                    * A non-lambda function can be passed only when the user
                      defined function does not accept any arguments other than
                      the mandatory input - the iterator on the partition of
                      rows.
                      A user can also use functools.partial and lambda functions
                      for the same, which are especially handy when:
                          * there is a need to pass positional and/or keyword
                            arguments (lambda).
                          * there is a need to pass keyword arguments only
                            (functool.partial).
                    * The return type of the user defined function must be one
                      of the following:
                          * numpy ndarray
                              * For a one-dimensional array, it is expected that
                                it has as many values as the number of expected
                                output columns.
                              * For a two-dimensional array, it is expected that
                                every array contained in the outer array has as
                                many values as the number of expected output
                                columns.
                          * pandas Series
                                This represents a row in the output, and the
                                number of values in it must be the same as the
                                number of expected output columns.
                          * pandas DataFrame
                                It is expected that a pandas DataFrame returned
                                by the "user_function" has the same number of
                                columns as the number of expected output columns.
                    * The return objects will be printed to the standard output
                      as required by Script using the 'quotechar' and 'delimiter'
                      values.
                    * The user function can also print the required output to
                      the standard output in the delimited (and possibly quoted)
                      format instead of returning an object of supported type.
 
            exec_mode:
                Optional Argument.
                Specifies the mode of execution for the user defined function.
                Permitted values:
                    * IN-DB: Execute the function on data in the teradataml
                             DataFrame in Vantage.
                    * LOCAL: Execute the function locally on sample data (at
                             most "num_rows" rows) from the teradataml
                             DataFrame.
                    * SANDBOX: Execute the function locally within a sandbox
                               environment on sample data (at most "num_rows"
                               rows) from the teradataml DataFrame.
                Default value: 'IN-DB'
                Types: str
 
            chunk_size:
                Optional Argument.
                Specifies the number of rows to be read in a chunk in each
                iteration using the iterator that will be passed to the user
                defined function.
                Varying the value passed to this argument affects the
                performance and the memory utilization.
                Default value: 1000
                Types: int
 
            num_rows:
                Optional Argument.
                Specifies the maximum number of sample rows to use from the
                teradataml DataFrame to apply the user defined function to when
                "exec_mode" is 'LOCAL' or 'SANDBOX'.
                Default value: 1000
                Types: int
 
            data_partition_column:
                Optional Argument.
                Specifies the Partition By columns for the teradataml DataFrame.
                Values to this argument can be provided as a list, if multiple
                columns are used for partition.
                Types: str OR list of Strings (str)
                Note:
                    * "data_partition_column" cannot be specified along with
                      "data_hash_column".
                    * "data_partition_column" cannot be specified along with
                      "is_local_order = True".
 
            data_hash_column:
                Optional Argument.
                Specifies the column to be used for hashing.
                The rows in the teradataml DataFrame are redistributed to AMPs
                based on the hash value of the column specified.
                The "user_function" then runs once on each AMP.
                If there is no "data_partition_column", then the entire result
                set, delivered by the function, constitutes a single group or
                partition.
                Types: str
                Note:
                    * "data_hash_column" cannot be specified along with
                      "data_partition_column".
                    * "is_local_order" must be set to 'True' when
                      "data_order_column" is used with "data_hash_column".
 
            returns:
                Optional Argument.
                Specifies the output column definition corresponding to the
                output of "user_function".
                When not specified, the function assumes that the names and
                types of the output columns are same as that of the input.
                Types: Dictionary specifying column name to
                       teradatasqlalchemy type mapping.
 
            delimiter:
                Optional Argument.
                Specifies a delimiter to use when reading columns from a row and
                writing result columns.
                Default value: '        '
                Types: str with one character
                Notes:
                    * This argument cannot be same as "quotechar" argument.
                    * This argument cannot be a newline character i.e., '
'.
 
            quotechar:
                Optional Argument.
                Specifies a character that forces all input and output of the
                user function to be quoted using this specified character.
                Using this argument enables the Advanced SQL Engine to
                distinguish between NULL fields and empty strings. A string with
                length zero is quoted, while NULL fields are not.
                If this character is found in the data, it will be escaped by a
                second quote character.
                Types: str with one character
                Notes:
                    * This argument cannot be same as "delimiter" argument.
                    * This argument cannot be a newline character i.e., '
'.
 
            auth:
                Optional Argument.
                Specifies an authorization to use when running the
                "user_function".
                Types: str
 
            charset:
                Optional Argument.
                Specifies the character encoding for data.
                Permitted values: 'utf-16', 'latin'
                Types: str
 
            data_order_column:
                Optional Argument.
                Specifies the Order By columns for the teradataml DataFrame.
                Values to this argument can be provided as a list, if multiple
                columns are used for ordering.
                This argument is used in both cases:
                "is_local_order = True" and "is_local_order = False".
                Types: str OR list of Strings (str)
                Note:
                    "is_local_order" must be set to 'True' when
                    "data_order_column" is used with "data_hash_column".
 
            is_local_order:
                Optional Argument.
                Specifies a boolean value to determine whether the input data
                is to be ordered locally or not.
                "data_order_column" with "is_local_order" set to 'False'
                specifies the order in which the values in a group, or
                partition, are sorted.
                When this argument is set to 'True', qualified rows on each AMP
                are ordered in preparation to be input to a table function.
                This argument is ignored, if "data_order_column" is None.
                Default value: False
                Types: bool
                Notes:
                    * "is_local_order" cannot be specified along with
                      "data_partition_column".
                    * When "is_local_order" is set to True, "data_order_column"
                      should be specified, and the columns specified in
                      "data_order_column" are used for local ordering.
 
            nulls_first:
                Optional Argument.
                Specifies a boolean value to determine whether NULLS are listed
                first or last during ordering.
                This argument is ignored, if "data_order_column" is None.
                NULLS are listed first when this argument is set to 'True', and
                last when set to 'False'.
                Default value: True
                Types: bool
 
            sort_ascending:
                Optional Argument.
                Specifies a boolean value to determine if the result set is to
                be sorted on the "data_order_column" column in ascending or
                descending order.
                The sorting is ascending when this argument is set to 'True',
                and descending when set to 'False'.
                This argument is ignored, if "data_order_column" is None.
                Default Value: True
                Types: bool
 
        RETURNS:
            1. teradataml DataFrame if exec_mode is "IN-DB".
            2. Pandas DataFrame if exec_mode is "LOCAL".
 
        RAISES:
             TypeError, TeradataMlException.
 
        EXAMPLES:
            >>> # This example uses the 'admissions_train' dataset, calculates
            >>> # the average 'gpa' per partition based on the value in
            >>> # 'admitted' column.
            >>> # Load the example data.
            >>> load_example_data("dataframe", "admissions_train")
            >>> df = DataFrame('admissions_train')
            >>> print(df)
               masters   gpa     stats programming  admitted
            id
            22     yes  3.46    Novice    Beginner         0
            36      no  3.00  Advanced      Novice         0
            15     yes  4.00  Advanced    Advanced         1
            38     yes  2.65  Advanced    Beginner         1
            5       no  3.44    Novice      Novice         0
            17      no  3.83  Advanced    Advanced         1
            34     yes  3.85  Advanced    Beginner         0
            13      no  4.00  Advanced      Novice         1
            26     yes  3.57  Advanced    Advanced         1
            19     yes  1.98  Advanced    Advanced         0
 
            >>> # Example 1:
            >>> # Create the user defined function to calculate the average
            >>> # 'gpa', by reading data in chunks.
            >>> # Note that the function accepts a TextFileReader object to
            >>> # iterate on data in chunks.
            >>> # The return type of the function is a numpy ndarray.
            >>>
            >>> from numpy import asarray
            >>> def grouped_gpa_avg(rows):
            ...     admitted = None
            ...     row_count = 0
            ...     gpa = 0
            ...     for chunk in rows:
            ...         for _, row in chunk.iterrows():
            ...             row_count += 1
            ...             gpa += row['gpa']
            ...             if admitted is None:
            ...                 admitted = row['admitted']
            ...     if row_count > 0:
            ...         return asarray([admitted, gpa/row_count])
            ...
            >>>
            >>> # Apply the user defined function to the DataFrame.
            >>> from teradatasqlalchemy.types import INTEGER, FLOAT
            >>> returns = OrderedDict([('admitted', INTEGER()),
            ...                        ('avg_gpa', FLOAT())])
            >>> avg_gpa_1 = df.map_partition(grouped_gpa_avg,
            ...                              returns = returns,
            ...                              data_partition_column = 'admitted')
            >>>
            >>> # Print the result.
            >>> print(avg_gpa_1)
               admitted   avg_gpa
            0         1  3.533462
            1         0  3.557143
 
            >>> # Example 2:
            >>> # Create the user defined function to calculate the average
            >>> # 'gpa', by reading data at once into a pandas DataFrame.
            >>> # Note that the function accepts a TextFileReader object to
            >>> # iterate on data in chunks.
            >>> # The return type of the function is a pandas Series.
            >>> def grouped_gpa_avg_2(rows):
            ...     pdf = rows.read()
            ...     if pdf.shape[0] > 0:
            ...         return pdf[['admitted', 'gpa']].mean()
            ...
            >>> avg_gpa_2 = df.map_partition(grouped_gpa_avg_2,
            ...                              returns = returns,
            ...                              data_partition_column = 'admitted')
            >>>
            >>> print(avg_gpa_2)
               admitted   avg_gpa
            0         0  3.557143
            1         1  3.533462
 
            >>> # Example 3:
            >>> # The following example demonstrates using a lambda function to
            >>> # achieve the same result.
            >>> # Note that the the function is written to accept an iterator
            >>> # (TextFileReader object), and return the result which is of
            >>> # type pandas Series.
            >>> avg_gpa_3 = df.map_partition(lambda rows: grouped_gpa_avg(rows),
            ...                              returns = returns,
            ...                              data_partition_column = 'admitted')
            >>>
            >>> print(avg_gpa_3)
               admitted   avg_gpa
            0         0  3.557143
            1         1  3.533462
 
            >>> # Example 4:
            >>> # The following example demonstrates using a function that
            >>> # returns the input data.
            >>> # Note that the the function is written to accept an iterator
            >>> # (TextFileReader object), and returns the result which is of
            >>> # type pandas DataFrame.
            >>> def echo(rows):
            ...     pdf = rows.read()
            ...     if pdf is not None:
            ...         return pdf
            ...
            >>> echo_out = df.map_partition(echo,
            ...                             data_partition_column = 'admitted')
            >>> print(echo_out)
               masters   gpa     stats programming  admitted
            id
            5       no  3.44    Novice      Novice         0
            7      yes  2.33    Novice      Novice         1
            22     yes  3.46    Novice    Beginner         0
            19     yes  1.98  Advanced    Advanced         0
            15     yes  4.00  Advanced    Advanced         1
            17      no  3.83  Advanced    Advanced         1
            34     yes  3.85  Advanced    Beginner         0
            13      no  4.00  Advanced      Novice         1
            36      no  3.00  Advanced      Novice         0
            40     yes  3.95    Novice    Beginner         0