teradataml.dataframe.window.lag = lag(offset_value=1, default_expression=None)

DESCRIPTION:
    The lag function accesses data from the row preceding 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: Execute the lag() function 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 lag() 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 lag() along
    #       with mean() window aggregate operations.
    >>> df = admissions_train.assign(previous_gpa=window.lag(), mean_gpa=window.mean())
    >>> df
       masters   gpa     stats programming  admitted  mean_gpa  previous_gpa
    id
    32     yes  3.46  Advanced    Beginner         0  3.660000          3.46
    35      no  3.68    Novice    Beginner         1  3.660000          3.50
    3       no  3.70    Novice    Beginner         1  3.660000          3.68
    39     yes  3.75  Advanced    Beginner         0  3.660000          3.70
    34     yes  3.85  Advanced    Beginner         0  3.660000          3.76
    21      no  3.87    Novice    Beginner         1  3.660000          3.85
    19     yes  1.98  Advanced    Advanced         0  3.615625           NaN
    11      no  3.13  Advanced    Advanced         1  3.615625          1.98
    14     yes  3.45  Advanced    Advanced         0  3.615625          3.13
    6      yes  3.50  Beginner    Advanced         1  3.615625          3.45
    >>>
 
    # Example 2: Retrieve the second preceding row from current row, for all columns
    #            in teradataml DataFrame, in a window, partitioned over
    #            'masters', and order by 'gpa'.
    # Create a window on teradataml DataFrame.
    >>> window = admissions_train.window(partition_columns="masters",
    ...                                  order_columns="gpa")
    >>>
    # Execute lag() on window.
    >>> df = window.lag(offset_value=2)
    >>> df
       masters   gpa     stats programming  admitted  admitted_lag  gpa_lag  id_lag masters_lag programming_lag stats_lag
    id
    38     yes  2.65  Advanced    Beginner         1           0.0     1.98    19.0         yes        Advanced  Advanced
    32     yes  3.46  Advanced    Beginner         0           1.0     2.65    38.0         yes        Beginner  Advanced
    22     yes  3.46    Novice    Beginner         0           0.0     3.45    14.0         yes        Advanced  Advanced
    4      yes  3.50  Beginner      Novice         1           0.0     3.46    32.0         yes        Beginner  Advanced
    6      yes  3.50  Beginner    Advanced         1           1.0     3.50     4.0         yes          Novice  Beginner
    26     yes  3.57  Advanced    Advanced         1           1.0     3.50    31.0         yes        Beginner  Advanced
    24      no  1.87  Advanced      Novice         1           NaN      NaN     NaN        None            None      None
    36      no  3.00  Advanced      Novice         0           NaN      NaN     NaN        None            None      None
    11      no  3.13  Advanced    Advanced         1           1.0     1.87    24.0          no          Novice  Advanced
    5       no  3.44    Novice      Novice         0           0.0     3.00    36.0          no          Novice  Advanced
    >>>