teradataml.geospatial.geodataframe.GeoDataFrame.assign = assign(self, drop_columns=False, **kwargs)

DESCRIPTION:
    Assign new columns to a teradataml GeoDataFrame.
 
PARAMETERS:
    drop_columns:
        Optional Argument.
        If True, drop columns that are not specified in assign.
        Note:
            When GeoDataFrame.assign() is run on GeoDataFrame.groupby(), this argument
            is ignored. In such cases, all columns are dropped and only new columns
            and grouping columns are returned.
        Default Value: False
        Types: bool
 
    kwargs:
        Specifies keyword-value pairs.
        - keywords are the column names.
        - values can be:
            * Column arithmetic expressions.
            * int/float/string literals.
            * GeoDataFrameColumn a.k.a. ColumnExpression Functions.
              (See GeoDataFrameColumn Functions in Function reference guide for more
               details)
            * DataFrameColumn a.k.a. ColumnExpression Functions.
              (See DataFrameColumn Functions in Function reference guide for more
               details)
            * SQLAlchemy ClauseElements.
              (See teradataml extension with SQLAlchemy in teradataml User Guide
               and Function reference guide for more details)
 
 
RETURNS:
    teradataml GeoDataFrame
    A new GeoDataFrame is returned with:
        1. New columns in addition to all the existing columns if "drop_columns" is False.
        2. Only new columns if "drop_columns" is True.
        3. New columns in addition to group by columns, i.e., columns used for grouping,
           if assign() is run on GeoDataFrame.groupby().
 
NOTES:
     1. The values in kwargs cannot be callable (functions).
     2. The original GeoDataFrame is not modified.
     3. Since ``kwargs`` is a dictionary, the order of your
       arguments may not be preserved. To make things predictable,
       the columns are inserted in alphabetical order, after the existing columns
       in the GeoDataFrame. Assigning multiple columns within the same ``assign`` is
       possible, but you cannot reference other columns created within the same
       ``assign`` call.
     4. The maximum number of columns that a GeoDataFrame can have is 2048.
     5. With GeoDataFrame.groupby(), only aggregate functions and literal values
       are advised to use. Other functions, such as string functions, can also be
       used, but the column used in such function must be a part of group by columns.
       See examples for teradataml extension with SQLAlchemy on using various
       functions with GeoDataFrame.assign().
 
RAISES:
     1. ValueError - When a callable is passed as a value, or columns from different
                     GeoDataFrames are passed as values in kwargs.
     2. TeradataMlException - When the return GeoDataFrame initialization fails, or
                              invalid argument types are passed.
 
EXAMPLES:
    >>> load_example_data("geodataframe", "sample_shapes")
    # Create a GeoDataFrame
    >>> gdf = GeoDataFrame("sample_shapes")
    >>> gdf = gdf.select(["skey", "points", "polygons"])
    >>>
    # In the example here, we will run following:
    #     1. Calculate the area of polygons.
    #     2. Get the dimensions of geometries in polygons.
    #     3. Check whether geometry in column polygons is 3D or not and they are valid or not.
    #     4. Get the max values for x, y and z coordinates in geometries in column "points".
    >>> gdf.assign(drop_columns=True,
    ...            skey = gdf.skey,
    ...            pol_area = gdf.polygons.area,
    ...            pol_dim = gdf.polygons.dimensions,
    ...            is_pol_3d = gdf.polygons.is_3D,
    ...            is_pol_valid = gdf.polygons.is_valid,
    ...            point_maxx = gdf.points.max_x,
    ...            point_maxy = gdf.points.max_y,
    ...            point_maxz = gdf.points.max_z
    ...           )
          is_pol_3d  is_pol_valid  point_maxx  point_maxy  point_maxz  pol_area pol_dim
    skey
    1006          1             0     235.520      54.546      7.4564       0.0    None
    1001          0             1      10.000      20.000         NaN     400.0    None
    1002          0             1       1.000       3.000         NaN     375.0    None
    1010          1             0      70.234      80.560     80.2340       0.0    None
    1004          1             1      10.000      20.000     30.0000     187.5    None
    1003          0             1     235.520      54.546         NaN     400.0    None
    1008          0             0      20.320       5.900         NaN     800.0    None
    1005          1             0       1.000       3.000      5.0000       0.0    None
    1007          0             1      20.000       5.000         NaN      62.5    None
    1009          1             1      70.000      80.000     80.0000    2000.0    None
    >>>