teradataml.dataframe.dataframe.DataFrame.unpivot = unpivot(self, columns=None, transpose_column=None, measure_columns=None, exclude_nulls=True, returns=None, all_columns=False, **kwargs)

DESCRIPTION:
    Rotate data from columns into rows to create easy-to-read DataFrames.  
 
PARAMETERS:
    columns:
        Required when keyword arguments are not specified, optional otherwise.
        Specifies the dictonary of column(s) with distinct column 
        value(s) used for unpivoting the data.
        Notes:
            * key is a column expression or tuple of column expressions.
            * value is a literal to be taken by column when transposed 
              into "transpose_column". If not specified, value is generated
              by the function based on column names.
            * Number of columns specified in each key should be equal.
        For example:
            columns={(df.Q101Sales, df.Q101Cogs): "2001_Q1",
                     (df.Q201Sales, df.Q201Cogs): None,
                     (df.Q301Sales, df.Q301Cogs): "2001_Q3"},
            transpose_column="yr_qtr",
            This example transposes columns 'Q101Sales' and 'Q101Cogs' 
            into a row where 'yr_qtr' column value would be '2001_Q1'.
            Similarly, 'Q301Sales' and 'Q301Cogs' into row 
            with '2001_Q3' value in 'yr_qtr' column.
            For 'Q201Sales' and 'Q201Cogs' value of 'yr_qtr' is
            function generated.
        Types: dict
 
    transpose_column:
        Required Argument.
        Specifies the name of the column in the output DataFrame, which holds 
        the data for columns specified in keys of "columns" argument.
        Types: str
    
    measure_columns:
        Required Argument. 
        Specifies the name(s) of output column(s) to unpivot the data in the columns
        specified in "columns" argument.
        Notes:
            * Number of columns specified in "measure_columns" should be equal 
              to number of columns in specified in each key of "columns".
            * One exception for above is when all the columns is to be unpivoted
              into a single column. In such case, "measure_columns" should be
              specified as a string or list of string with one value.
        Types: str or list of str (string)
    
    exclude_nulls:
        Optional Argument.
        Specifies whether to exclude NULL(None) values while unpivoting the data.
        When set to True, excludes NULL(None), otherwise includes NULL.
        Default Value: True
        Types: bool
    
    returns:
        Optional Argument.
        Specifies the custom column name(s) to be returned in the output DataFrame.
        Notes:
            * Number of column names should be equal to one greater than number in
              "measure_column". 
            * All columns including columns in DataFrame which do not participate 
              in unpivot must be specified if "all_columns" is set to True.
        Types: str OR list of Strings (str)
    
    all_columns:
        Optional Argument.
        Specifies whether "returns" argument should include the names of only unpivot 
        columns or all columns.
        When set to True, all columns including columns in DataFrame which do not
        participate in unpivot must be specified.
        When set to False, only output columns excluding columns in DataFrame which do not
        participate in unpivot must be specified.
        Default Value: False
        Types: bool
    
    **kwargs:
        Specifies the keyword argument to accept column name and column value(s)
        as named arguments.
        For example:
            col1=df.year, col1_value=2001, col2=df.qtr, col2_value='Q1'
            or 
            col1=(df.Q101Sales, df.Q101Cogs), col1_value="2001_Q1",
            col2=(df.Q201Sales, df.Q201Cogs), col2_value=None,
            col3=(df.Q301Sales, df.Q301Cogs), col3_value="2001_Q3"
        Notes:
            * Either use "columns" argument or keyword arguments.
            * Format for column name arguments should be col1, col2,.. colN with
              values of type ColumnExpression.
            * Format for column value argument should be col1_value, col2_value,.. colN_value.
              
    
RETURNS:
        teradataml DataFrame
        Notes:
            * The columns which are not participating in unpivoting always aligned to 
              left most in the output DataFrame. 
            * Order of unpivot columns in output DataFrame follows the same order as the 
              values specified in argument "columns" or the order in keyword arguments. 
            * The output columns are named according to the values specified in 
              "transpose_column" and "measure_columns" or "returns" argument.
 
 
RAISES:
    TypeError, ValueError, TeradataMLException
 
 
EXAMPLES:
    # Create a teradataml DataFrame.
    >>> load_example_data("teradataml", "star1")
    >>> df = DataFrame("star1")
    >>> print(df)
            state    yr qtr  sales  cogs
    country
    USA        NY  2001  Q1   45.0  25.0
    CANADA     ON  2001  Q2   10.0   0.0
    CANADA     BC  2001  Q3   10.0   0.0
    USA        CA  2002  Q2   50.0  20.0
    USA        CA  2002  Q1   30.0  15.0
 
    # Create a pivot DataFrame. 
    >>> df = df.pivot(columns={df.qtr: ["Q1", "Q2", "Q3"], df.yr: ["2001"]},
    ...               aggfuncs=[df.sales.sum(), df.cogs.sum()],
    ...               returns=["Q101Sales", "Q201Sales", "Q301Sales",
    ...                        "Q101Cogs", "Q201Cogs", "Q301Cogs"])
    >>> print(df)
      country state  Q101Sales  Q201Sales  Q301Sales  Q101Cogs  Q201Cogs  Q301Cogs
    0  CANADA    BC        NaN        NaN        NaN       NaN      10.0       0.0
    1  CANADA    ON        NaN        NaN       10.0       0.0       NaN       NaN
    2     USA    NY       45.0       25.0        NaN       NaN       NaN       NaN
    3     USA    CA        NaN        NaN        NaN       NaN       NaN       NaN
    
    # Example 1: Unpivot quarterly sales data to 'sales' column and quarterly 
    #            cogs data to 'cogs' columns using "columns" argument.
    >>> unpivot_df = df.unpivot(columns={(df.Q101Sales, df.Q101Cogs): "2001_Q1",
    ...                                  (df.Q201Sales, df.Q201Cogs): None,
    ...                                  (df.Q301Sales, df.Q301Cogs): "2001_Q3"},
    ...                         transpose_column="yr_qtr",
    ...                         measure_columns=["sales", "cogs"])
    >>> print(unpivot_df)
      country state              yr_qtr  sales  cogs
    0  CANADA    BC  Q201Sales_Q201Cogs    NaN  10.0
    1  CANADA    ON             2001_Q1    NaN   0.0
    2  CANADA    ON             2001_Q3   10.0   NaN
    3  CANADA    BC             2001_Q3    NaN   0.0
    4     USA    NY  Q201Sales_Q201Cogs   25.0   NaN
    5     USA    NY             2001_Q1   45.0   NaN
 
    # Example 2: Unpivot 'sales' and 'cogs' in to a single column 'sales_cogs'.
    >>> unpivot_df = df.unpivot(columns={(df.Q101Sales, df.Q101Cogs,
    ...                                  df.Q201Sales, df.Q201Cogs,
    ...                                  df.Q301Sales, df.Q301Cogs): None},
    ...                         transpose_column="yr_qtr",
    ...                         measure_columns="sales_cogs")
    >>> print(unpivot_df)
      country state     yr_qtr  sales_cogs
    0  CANADA    BC   Q201Cogs        10.0
    1  CANADA    ON   Q101Cogs         0.0
    2  CANADA    ON  Q301Sales        10.0
    3  CANADA    BC   Q301Cogs         0.0
    4     USA    NY  Q201Sales        25.0
    5     USA    NY  Q101Sales        45.0
 
    # Example 3: Unpivot quarterly sales data to 'sales' column and quarterly 
    #            cogs data to 'cogs' columns using keyword arguments.    
    >>> unpivot_df = df.unpivot(transpose_column="yr_qtr",
    ...                         measure_columns=["sales", "cogs"],
    ...                         col1 = (df.Q101Sales, df.Q101Cogs),
    ...                         col1_value = "Q101",
    ...                         col2 = (df.Q201Sales, df.Q201Cogs),
    ...                         col2_value = None,
    ...                         col3 = (df.Q301Sales, df.Q301Cogs),
    ...                         col3_value = "Q103")
    >>> print(unpivot_df)
      country state              yr_qtr  sales  cogs
    0  CANADA    BC  Q201Sales_Q201Cogs    NaN  10.0
    1  CANADA    ON                Q101    NaN   0.0
    2  CANADA    ON                Q103   10.0   NaN
    3  CANADA    BC                Q103    NaN   0.0
    4     USA    NY  Q201Sales_Q201Cogs   25.0   NaN
    5     USA    NY                Q101   45.0   NaN
 
 
    # Example 4: Unpivot quarterly sales data to 'sales' column and quarterly
    #            cogs data to 'cogs' columns and rename column of the
    #            output using "returns" argument.
    >>> unpivot_df = df.unpivot(columns={(df.Q101Sales, df.Q101Cogs): "Q101",
    ...                                  (df.Q201Sales, df.Q201Cogs): None,
    ...                                  (df.Q301Sales, df.Q301Cogs): "Q301"},
    ...                         transpose_column="yr_qtr",
    ...                         measure_columns=["sales", "cogs"],
    ...                         returns=["year_quarter", "sales_data", "cogs_data"])
    >>> print(unpivot_df)
      country state        year_quarter  sales_data  cogs_data
    0  CANADA    BC  Q201Sales_Q201Cogs         NaN       10.0
    1  CANADA    ON                Q101         NaN        0.0
    2  CANADA    ON                Q301        10.0        NaN
    3  CANADA    BC                Q301         NaN        0.0
    4     USA    NY  Q201Sales_Q201Cogs        25.0        NaN
    5     USA    NY                Q101        45.0        NaN
 
    # Example 5: Unpivot quarterly sales data to 'sales' column and quarterly
    #            cogs data to 'cogs' columns and rename each column of the
    #            output using "returns" and "all_columns" argument.
    >>> unpivot_df = df.unpivot(columns={(df.Q101Sales, df.Q101Cogs): "Q101",
    ...                                  (df.Q201Sales, df.Q201Cogs): None,
    ...                                  (df.Q301Sales, df.Q301Cogs): "Q301"},
    ...                         transpose_column="yr_qtr",
    ...                         measure_columns=["sales", "cogs"],
    ...                         returns=["con", "st", "year_quarter",
    ...                                  "sales_data", "cogs_data"],
    ...                         all_columns=True)
    >>> print(unpivot_df)
          con  st        year_quarter  sales_data  cogs_data
    0  CANADA  BC  Q201Sales_Q201Cogs         NaN       10.0
    1  CANADA  ON                Q101         NaN        0.0
    2  CANADA  ON                Q301        10.0        NaN
    3  CANADA  BC                Q301         NaN        0.0
    4     USA  NY  Q201Sales_Q201Cogs        25.0        NaN
    5     USA  NY                Q101        45.0        NaN
 
    # Example 6: Unpivot quarterly sales data to 'sales' column and quarterly
    #            cogs data to 'cogs' columns by including NULLs.
    >>> unpivot_df = df.unpivot(columns={(df.Q101Sales, df.Q101Cogs): "2001_Q1",
    ...                                  (df.Q201Sales, df.Q201Cogs): None,
    ...                                  (df.Q301Sales, df.Q301Cogs): "2001_Q3"},
    ...                         transpose_column="yr_qtr",
    ...                         measure_columns=["sales", "cogs"],
    ...                         exclude_nulls=False)
    >>> print(unpivot_df)
      country state              yr_qtr  sales  cogs
    0     USA    CA             2001_Q3    NaN   NaN
    1     USA    NY  Q201Sales_Q201Cogs   25.0   NaN
    2     USA    NY             2001_Q3    NaN   NaN
    3  CANADA    BC             2001_Q1    NaN   NaN
    4  CANADA    BC             2001_Q3    NaN   0.0
    5  CANADA    ON             2001_Q1    NaN   0.0
    6  CANADA    BC  Q201Sales_Q201Cogs    NaN  10.0
    7     USA    NY             2001_Q1   45.0   NaN
    8     USA    CA  Q201Sales_Q201Cogs    NaN   NaN
    9     USA    CA             2001_Q1    NaN   NaN