teradataml.dataframe.sql.DataFrameColumn.months_between = months_between(self, expression)

DESCRIPTION:
    Function returns the number of months between value in specified date or timestamp value in a column as a
    literal and date or timestamp value in argument.
    It returns an integer value only when the two dates are same else it returns the fractional portion of the
    result based on a 31-day month.
 
PARAMETERS:
    expression:
        Optional Argument.
        Specifies a date or timestamp or timestamp with time zone value.
        Types: DataFrameColumn
        Notes:
            1. If expression is NULL, NULL is returned.
            2. Both date_timestamp_value1 and date_timestamp_value2 should be of the same type.
            3. Since TIMESTAMP values are stored in UTC time within the database and lack a time zone, the session
               time zone is used to interpret the time stamp value within the function.
               For TIMESTAMP WITH TIME ZONE values, the time zone component is used to interpret the time stamp
               value within the function.
            4. If expression is:
                    Later than DataFrameColumn value, the result is negative.
                    Earlier than DataFrameColumn value, the result is positive.
            5. If DataFrameColumn value and expression are either the same days of the month or both last days of
               months, the result is always an integer. Otherwise, MONTHS_BETWEEN calculates the fractional portion
               of the result based on a 31-day month and considers the difference in time components of
               DataFrameColumn value and expression.
            6. The Gregorian calendar is supported.
            7. Timestamps without a time zone are compared in the local time zone. This matters solely for the
               purpose of determining if two timestamps reside on the same day or are both the last day of a month.
               Timestamps with a time zone are converted to UTC before being compared in order to ensure the times
               are in the same zone.
 
RAISES:
    TypeError, ValueError, TeradataMlException
 
RETURNS:
    DataFrameColumn
 
EXAMPLES:
    # Load the data to run the example.
    >>> load_example_data("dataframe", ["sales"])
 
    # Create a DataFrame on 'sales' table.
    >>> df = DataFrame.from_table('sales')
 
    # Preparing the data.
    >>> df_sales = df.assign(dates = case([(df.accounts == 'Alpha Co', df.datetime + random.randrange(20,1000,3)),
                            (df.accounts == 'Blue Inc', df.datetime + random.randrange(20,1000,3)),
                            (df.accounts == 'Jones LLC', df.datetime + random.randrange(20,1000,3)),
                            (df.accounts == 'Orange Inc', df.datetime + random.randrange(20,1000,3)),
                            (df.accounts == 'Yellow Inc', df.datetime + random.randrange(20,1000,3)),
                            (df.accounts == 'Red Inc', df.datetime + random.randrange(20,1000,3))]))
 
    # Example 1: Returns the number of months between value in specified date or timestamp value in a column as a
    #            literal and date or timestamp value in argument. It returns an integer value only when the two
    #            dates are same else it returns the fractional portion of the result based on a 31-day month
    >>> df = df_sales.assign(res = df_sales.dates.months_between(df_sales.datetime))
    >>> print(df)
                  Feb    Jan    Mar    Apr    datetime     dates        res
    accounts
    Alpha Co    210.0  200.0  215.0  250.0  04/01/2017  18/03/20  14.516129
    Blue Inc     90.0   50.0   95.0  101.0  04/01/2017  19/02/25  25.677419
    Jones LLC   200.0  150.0  140.0  180.0  04/01/2017  17/04/27   3.741935
    Orange Inc  210.0    NaN    NaN  250.0  04/01/2017  19/05/29  28.806452
    Yellow Inc   90.0    NaN    NaN    NaN  04/01/2017  18/10/22  21.580645
    Red Inc     200.0  150.0  140.0    NaN  04/01/2017  17/08/07   7.096774