Teradata Python Package Function Reference - 16.20 - SeriesSplitter - 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.SeriesSplitter = class SeriesSplitter(builtins.object)
     Methods defined here:
__init__(self, data=None, partition_columns=None, duplicate_rows_count=1, order_by_columns=None, split_count=4, rows_per_split=1000, accumulate=None, split_id_column='split_id', return_stats_table=True, values_before_first='-1', values_after_last='null', duplicate_column=None, partial_split_id=False, data_sequence_column=None)
DESCRIPTION:
    The SeriesSplitter function splits partitions into subpartitions 
    (called splits) to balance the partitions for time series 
    manipulation. The function creates an additional column that contains 
    split identifiers. Each row contains the identifier of the split to 
    which the row belongs. Optionally, the function also copies a 
    specified number of boundary rows to each split.
 
 
PARAMETERS:
    data:
        Required Argument.
        Specifies the name of the input teradataml DataFrame to be split.
    
    partition_columns:
        Required Argument.
        Specifies the partitioning columns of teradataml DataFrame.
        These columns determines the identity of a partition.
        Types: str OR list of Strings (str)
 
    duplicate_rows_count:
        Optional Argument.
        Specifies the number of rows to duplicate across split boundaries.
        By default, the function duplicates one row from the previous
        partition and one row from the next partition. If you specify
        only one value v1, then the function duplicates v1 rows from the
        previous partition and v1 rows from the next partition. If you
        specify two values v1 and v2, then the function duplicates v1
        rows from the previous partition and v2 rows from the next
        partition. Each argument value must be non-negative integer
        less than or equal to 1000.
        Default Value: 1
        Types: int or list of Integers (int)
 
    order_by_columns:
        Optional Argument.
        Specifies the ordering columns of teradataml DataFrame. These
        columns establish the order of the rows and splits. Without
        this argument, the function can split the rows in any order.
        Types: str OR list of Strings (str)
 
    split_count:
        Optional Argument.
        Specifies the desired number of splits in a partition of the output
        table. The value of "split_count" must be a positive int, and
        its upper bound is the number of rows in the partition.
        Note:  If underlying table on Vantage, pointed by 'data', has
               multiple partitions, then you cannot specify "split_count". Instead,
               specify "rows_per_split". Base the value of "split_count" on the
               desired amount of parallelism.
               For example, for a cluster with 10 vworkers, make "split_count"
               a multiple of 10. If the number of rows in teradataml DataFrame
               (n) is not exactly divisible by "split_count", then the function
               estimates the number of splits in the partition, using this formula:
               ceiling (n / ceiling (n / split_count) )
        Default Value: 4
        Types: int
 
    rows_per_split:
        Optional Argument.
        Specifies the desired maximum number of rows in each split in
        the output teradataml DataFrame. If the number of rows in
        input table is not exactly divisible by "rows_per_split", then
        the last split contains fewer than "rows_per_split" rows, but
        no row contains more than "rows_per_split" rows. The value of
        "rows_per_split" must be a positive int.
        Note: If underlying table on Vantage, pointed by 'data', has
              multiple partitions, then specify "rows_per_split" instead of
              "split_count".
        Default Value: 1000
        Types: int
 
    accumulate:
        Optional Argument.
        Specifies the names of teradataml DataFrame columns (other than
        those specified by "partition_columns" and "order_by_columns") to
        copy to the output teradataml DataFrame. By default, only the
        columns specified by "partition_columns" and "order_by_columns" are
        copied to the output teradataml DataFrame.
        Types: str OR list of Strings (str)
 
    split_id_column:
        Optional Argument.
        Specifies the name for the output teradataml DataFrame column
        to contain the split identifiers. If the output teradataml
        DataFrame  has another column name as that specified in
        "split_id_column", the function returns an error. Therefore, if
        the output teradataml DataFrame has a column named 'split_id'
        (specified by "accumulate", "partition_columns", or
        "order_by_columns"), you must use "split_id_column" to specify
        a different value.
        Default Value: "split_id"
        Types: str
 
    return_stats_table:
        Optional Argument.
        Specifies whether the function returns the data in "stats_table"
        output teradataml DataFrame. When this value is "False", the
        function returns only the data in "output_table" output
        teradataml DataFrame.
        Default Value: True
        Types: bool
 
    values_before_first:
        Optional Argument.
        If "duplicate_rows_count" is nonzero and "order_by_columns" is
        specified, then "values_before_first" specifies the values to be
        stored in the ordering columns that precede the first row of
        the first split in a partition as a result of duplicating rows
        across split boundaries. If "values_before_first" specifies only
        one value and "order_by_columns" specifies multiple ordering columns,
        then the specified value is stored in every ordering column.
        If "values_before_first" specifies multiple values, then it must
        specify a value for each ordering column. The value and the
        ordering column must have the same data type. For the data type
        str, the values are case-insensitive. The values for different
        data types are:
            int: -1,
            str : "-1",
            Date or time-based: 1900-01-01 0:00:00,
            Boolean: False
        Default Value: "-1"
        Types: str
 
    values_after_last:
        Optional Argument.
        If "duplicate_rows_count" is nonzero and orde_by_columns is
        specified, then "values_after_last" specifies the values to be
        stored in the ordering columns that follow the last row of the
        last split in a partition as a result of duplicating rows across
        split boundaries. If "values_after_last" specifies only one value
        and "order_by_columns" specifies multiple ordering columns, then
        the specified value is stored in every ordering column. If
        "values_after_last" specifies multiple values, then it must specify
        a value for each ordering column. The value and the ordering
        column must have the same data type.  For the data type str, the
        values are case-insensitive.
        Default Value: "null"
        Types: str
 
    duplicate_column:
        Optional Argument.
        Specifies the name of the column that indicates whether a row is
        duplicated from the neighboring split. If the row is duplicated,
        this column contains 1; otherwise it contains 0.
        Types: str
 
    partial_split_id:
        Optional Argument.
        Specifies whether "split_id_column" contains only the numeric split
        identifier. If the value is "True", then "split_id_column"
        contains a numeric representation of the split identifier that
        is unique for each partition. To distribute the output
        teradataml DataFrame by split, use a combination of all
        partitioning columns and "split_id_column". If the value is "False",
        then "split_id_column" contains a string representation of the
        split that is unique across all partitions. The function
        generates the string representation by concatenating the
        partitioning columns with the order of the split inside the
        partition (the numeric representation). In the string
        representation, hyphens separate partitioning column names from
        each other and from the order. For example, "pcol1- pcol2-3".
        Default Value: False
        Types: bool
 
    data_sequence_column:
        Optional Argument.
        Specifies the list of column(s) that uniquely identifies each row of
        the input argument "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)
 
RETURNS:
    Instance of SeriesSplitter.
    Output teradataml DataFrames can be accessed using attribute
    references, such as SeriesSplitterObj.<attribute_name>.
    Output teradataml DataFrame attribute names are:
        1. output_table
        2. stats_table
        3. output
 
    When the argument "return_stats_table" is set to True, all the three
    output teradataml DataFrames are generated. But, when the argument
    'return_stats_table' is False, the "stats_table" output teradataml
    DataFrame will not be generated.
 
 
 
RAISES:
    TeradataMlException
 
 
EXAMPLES:
    # Load example data.
    load_example_data("seriessplitter", "ibm_stock")
 
    # Create teradataml DataFrame objects.
    # The input table has the daily stock prices from 1961 to 1962.
    ibm_stock = DataFrame.from_table("ibm_stock")
 
    # Example 1 - This examples splits the time series stock data into
    # subpartitions.
    SeriesSplitter_out1 = SeriesSplitter(data = ibm_stock,
                                        partition_columns = ["name"],
                                        order_by_columns = ["period"],
                                        split_count = 50,
                                        accumulate = ["stockprice"]
                                        )
 
    # Print the results
    print(SeriesSplitter_out1.output_table)
    print(SeriesSplitter_out1.stats_table)
    print(SeriesSplitter_out1.output)
 
   # Example 2 - In the example "return_stats_table" is False which returns
   # only the output_table.
   SeriesSplitter_out2 = SeriesSplitter(data=ibm_stock,
                                        partition_columns='name',
                                        order_by_columns = 'period',
                                        split_count = 9,
                                        split_id_column = 'split_id',
                                        duplicate_rows_count = [1,1],
                                        return_stats_table = False,
                                        accumulate = 'stockprice',
                                        values_before_first = "1961-01-01",
                                        values_after_last = "NULL",
                                        partial_split_id = False
                                        )
   # Print the results
   print(SeriesSplitter_out1.output_table)
   print(SeriesSplitter_out1.output)
 
   # Note: When argument return_stats_table is False output teradataml DataFrame,
   #       (stats_table) is not created. If tried to access this attribute
   #       an INFO message will be thrown mentioning the same.
__repr__(self)
Returns the string representation for a SeriesSplitter class instance.