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

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
November 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)
teradataml.dataframe.window.lead = lead(offset_value=1, default_expression=None)
DESCRIPTION:
    The lead function accesses data from the row following the current row at
    a specified offset value over the specified window in a teradataml DataFrame
    or ColumnExpression.
 
PARAMETERS:
    offset_value:
        Optional Argument.
        Specifies the physical row position relative to the current row in
        a given window of rows. "offset_value" must be greater than or equal
        to 0 and less than or equal to 4096. An "offset_value" of 0 specifies
        the current row.
        Default Value: 1
        types: int
 
    default_expression:
        Optional Argument.
        Specifies the default value to be used as return value in case function
        does not return any value. The data type of "default_expression" should match
        with the data type of ColumnExpression.
        Default Value: None
        types: ColumnExpression OR float OR int OR str
 
RETURNS:
    * teradataml DataFrame - When aggregate is executed using window created
      on teradataml DataFrame.
    * ColumnExpression, also known as, teradataml DataFrameColumn - When aggregate is
      executed using window created on ColumnExpression.
 
RAISES:
    RuntimeError - If column does not support the aggregate operation.
 
EXAMPLES:
    # Load the data to run the example.
    >>> load_example_data("dataframe", "admissions_train")
    >>>
 
    # Create a teradataml DataFrame on 'admissions_train' table.
    >>> admissions_train = DataFrame("admissions_train")
    >>> admissions_train
       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: Retrieve the following row from current row over the
    #            rows in a window, partitioned over 'programming'
    #            and sort by 'gpa'.
    # Create a window on 'gpa'.
    >>> window = admissions_train.gpa.window(partition_columns="programming",
    ...                                      order_columns="gpa")
    # Execute lead() on the window and attach it to the teradataml DataFrame.
    # Note: DataFrame.assign() allows combining multiple window aggregate operations
    #       in one single call. In this example, we are executing lead() along
    #       with mean() window aggregate operations.
    >>> df = admissions_train.assign(following_gpa=window.lead(), mean_gpa=window.mean())
    >>> df
       masters   gpa     stats programming  admitted  following_gpa  mean_gpa
    id
    32     yes  3.46  Advanced    Beginner         0           3.50  3.660000
    35      no  3.68    Novice    Beginner         1           3.70  3.660000
    3       no  3.70    Novice    Beginner         1           3.75  3.660000
    39     yes  3.75  Advanced    Beginner         0           3.76  3.660000
    34     yes  3.85  Advanced    Beginner         0           3.87  3.660000
    21      no  3.87    Novice    Beginner         1           3.95  3.660000
    19     yes  1.98  Advanced    Advanced         0           3.13  3.615625
    11      no  3.13  Advanced    Advanced         1           3.45  3.615625
    14     yes  3.45  Advanced    Advanced         0           3.50  3.615625
    6      yes  3.50  Beginner    Advanced         1           3.57  3.615625
    >>>
 
    # Example 2: Retrieve the second following row from current row, for all columns
    #            in teradataml DataFrame, in an window, partitioned over
    #            'masters', and order by 'gpa'.
    # Create an window on teradataml DataFrame.
    >>> window = admissions_train.window(partition_columns="masters",
    ...                                  order_columns="gpa")
    >>>
    # Execute lead() on window.
    >>> df = window.lead(offset_value=2)
    >>> df
       masters   gpa     stats programming  admitted  admitted_lead  gpa_lead  id_lead masters_lead programming_lead stats_lead
    id
    38     yes  2.65  Advanced    Beginner         1              0      3.45       14          yes         Advanced   Advanced
    32     yes  3.46  Advanced    Beginner         0              0      3.46       22          yes         Beginner     Novice
    22     yes  3.46    Novice    Beginner         0              1      3.50        4          yes           Novice   Beginner
    4      yes  3.50  Beginner      Novice         1              1      3.50       31          yes         Beginner   Advanced
    6      yes  3.50  Beginner    Advanced         1              1      3.57       26          yes         Advanced   Advanced
    26     yes  3.57  Advanced    Advanced         1              1      3.59       23          yes           Novice   Advanced
    24      no  1.87  Advanced      Novice         1              0      3.00       36           no           Novice   Advanced
    36      no  3.00  Advanced      Novice         0              1      3.13       11           no         Advanced   Advanced
    11      no  3.13  Advanced    Advanced         1              0      3.44        5           no           Novice     Novice
    5       no  3.44    Novice      Novice         0              1      3.52       37           no           Novice     Novice
    >>>