teradataml.geospatial.geodataframe.GeoDataFrame.plot = plot(self, x=None, y=None, kind='geometry', **kwargs)

DESCRIPTION:
    Generate plots on teradataml GeoDataFrame. Following type of plots
    are supported, which can be specified using argument "kind":
        * geometry plot
        * bar plot
        * corr plot
        * line plot
        * mesh plot
        * scatter plot
        * wiggle plot
    Notes:
        * Geometry plot is generated based on geometry column in teradataml GeoDataFrame.
        * Only the columns with ST_GEOMETRY type are allowed for generating geometry plot.
        * The maximum size for ST_GEOMETRY must be less than or equal to 64000.
        * The ST_GEOMETRY shape can be POINT, LINESTRING etc. It is POLGYON that allows
          filling of different colors.
 
PARAMETERS:
    x:
        Optional Argument.
        Specifies a GeoDataFrame column to use for the x-axis data.
        Note:
            "x" is not significant for geometry plots. For other plots
            it is mandatory argument.
        Types: teradataml GeoDataFrame Column
 
    y:
        Required Argument.
        Specifies GeoDataFrame column(s) to use for the y-axis data.
        Notes:
             * Geometry plot always requires geometry column and corresponding 'weight'
               column. 'weight' column represents the weight of a shape mentioned in
               geometry column.
             * If user does not specify geometry column, the default geometry column
               is considered for plotting.
        Types: teradataml GeoDataFrame Column OR tuple of GeoDataFrame Column OR list of teradataml GeoDataFrame Columns.
 
    scale:
        Optional Argument.
        Specifies GeoDataFrame column to use for scale data to
        wiggle and mesh plots.
        Note:
            "scale" is significant for wiggle and mesh plots. Ignored for other
            type of plots.
        Types: teradataml GeoDataFrame Column.
 
    kind:
        Optional Argument.
        Specifies the kind of plot.
        Permitted Values:
            * 'geometry'
            * 'line'
            * 'bar'
            * 'scatter'
            * 'corr'
            * 'wiggle'
            * 'mesh'
        Default Value: geometry
        Types: str
 
    ax:
        Optional Argument.
        Specifies the axis for the plot.
        Types: Axis
 
    cmap:
        Optional Argument.
        Specifies the name of the colormap to be used for plotting.
        Notes:
             * Significant only when corresponding type of plot is mesh or geometry.
             * Ignored for other type of plots.
        Permitted Values:
            * All the colormaps mentioned in below URLs are supported.
                * https://matplotlib.org/stable/tutorials/colors/colormaps.html
                * https://matplotlib.org/cmocean/
        Types: str
 
    color:
        Optional Argument.
        Specifies the color for the plot.
        Note:
            Hexadecimal color codes are not supported.
        Permitted Values:
            * 'blue'
            * 'orange'
            * 'green'
            * 'red'
            * 'purple'
            * 'brown'
            * 'pink'
            * 'gray'
            * 'olive'
            * 'cyan'
            * Apart from above mentioned colors, the colors mentioned in
              https://xkcd.com/color/rgb are also supported.
        Default Value: 'blue'
        Types: str OR list of str
 
    figure:
        Optional Argument.
        Specifies the figure for the plot.
        Types: Figure
 
    figsize:
        Optional Argument.
        Specifies the size of the figure in a tuple of 2 elements. First
        element represents width of plot image in pixels and second
        element represents height of plot image in pixels.
        Default Value: (640, 480)
        Types: tuple
 
    figtype:
        Optional Argument.
        Specifies the type of the image to generate.
        Permitted Values:
            * 'png'
            * 'jpg'
            * 'svg'
        Default Value: png
        Types: str
 
    figdpi:
        Optional Argument.
        Specifies the dots per inch for the plot image.
        Note:
            * Valid range for "dpi" is: 72 <= width <= 300.
        Default Value: 100 for PNG and JPG Type image.
        Types: int
 
    grid_color:
        Optional Argument.
        Specifies the color of the grid.
        Note:
            Hexadecimal color codes are not supported.
        Permitted Values:
            * 'blue'
            * 'orange'
            * 'green'
            * 'red'
            * 'purple'
            * 'brown'
            * 'pink'
            * 'gray'
            * 'olive'
            * 'cyan'
            * Apart from above mentioned colors, the colors mentioned in
              https://xkcd.com/color/rgb are also supported.
        Default Value: gray
        Types: str
 
    grid_format:
        Optional Argument.
        Specifies the format for the grid.
        Types: str
 
    grid_linestyle:
        Optional Argument.
        Specifies the line style of the grid.
        Permitted Values:
            * -
            * --
            * -.
        Default Value: -
        Types: str
 
    grid_linewidth:
        Optional Argument.
        Specifies the line width of the grid.
        Note:
            Valid range for "grid_linewidth" is: 0.5 <= grid_linewidth <= 10.
        Default Value: 0.8
        Types: int OR float
 
    heading:
        Optional Argument.
        Specifies the heading for the plot.
        Types: str
 
    legend:
        Optional Argument.
        Specifies the legend(s) for the Plot.
        Types: str OR list of str
 
    legend_style:
        Optional Argument.
        Specifies the location for legend to display on Plot image. By default,
        legend is displayed at upper right corner.
        Permitted Values:
            * 'upper right'
            * 'upper left'
            * 'lower right'
            * 'lower left'
            * 'right'
            * 'center left'
            * 'center right'
            * 'lower center'
            * 'upper center'
            * 'center'
        Default Value: 'upper right'
        Types: str
 
    linestyle:
        Optional Argument.
        Specifies the line style for the plot.
        Permitted Values:
            * -
            * --
            * -.
            * :
        Default Value: -
        Types: str OR list of str
 
    linewidth:
        Optional Argument.
        Specifies the line width for the plot.
        Note:
            Valid range for "linewidth" is: 0.5 <= linewidth <= 10.
        Default Value: 0.8
        Types: int OR float OR list of int OR list of float
 
    marker:
        Optional Argument.
        Specifies the type of the marker to be used.
        Permitted Values:
            All the markers mentioned in https://matplotlib.org/stable/api/markers_api.html
            are supported.
        Types: str OR list of str
 
    markersize:
        Optional Argument.
        Specifies the size of the marker.
        Note:
            Valid range for "markersize" is: 1 <= markersize <= 20.
        Default Value: 6
        Types: int OR float OR list of int OR list of float
 
    position:
        Optional Argument.
        Specifies the position of the axis in the figure. Accepts a tuple
        of two elements where first element represents the row and second
        element represents column.
        Default Value: (1, 1)
        Types: tuple
 
    span:
        Optional Argument.
        Specifies the span of the axis in the figure. Accepts a tuple
        of two elements where first element represents the row and second
        element represents column.
        For Example,
            Span of (2, 1) specifies the Axis occupies 2 rows and 1 column
            in Figure.
        Default Value: (1, 1)
        Types: tuple
 
    reverse_xaxis:
        Optional Argument.
        Specifies whether to reverse tick values on x-axis or not.
        Default Value: False
        Types: bool
 
    reverse_yaxis:
        Optional Argument.
        Specifies whether to reverse tick values on y-axis or not.
        Default Value: False
        Types: bool
 
    series_identifier:
        Optional Argument.
        Specifies the teradataml GeoDataFrame Column which represents the
        identifier for the data. As many plots as distinct "series_identifier"
        are generated in a single Axis.
        For example:
            consider the below data in teradataml GeoDataFrame.
                   ID   x   y
                0  1    1   1
                1  1    2   2
                2  2   10  10
                3  2   20  20
            If "series_identifier" is not specified, simple plot is
            generated where every 'y' is plotted against 'x' in a
            single plot. However, specifying "series_identifier" as 'ID'
            generates two plots in a single axis. One plot is for ID 1
            and another plot is for ID 2.
        Types: teradataml GeoDataFrame Column.
 
    title:
        Optional Argument.
        Specifies the title for the Axis.
        Types: str
 
    xlabel:
        Optional Argument.
        Specifies the label for x-axis.
        Notes:
             * When set to empty string, label is not displayed for x-axis.
             * When set to None, name of the x-axis column is displayed as
               label.
        Types: str
 
    xlim:
        Optional Argument.
        Specifies the range for xtick values.
        Types: tuple
 
    xtick_format:
        Optional Argument.
        Specifies whether to format tick values for x-axis or not.
        Types: str
 
    ylabel:
        Optional Argument.
        Specifies the label for y-axis.
        Notes:
             * When set to empty string, label is not displayed for y-axis.
             * When set to None, name of the y-axis column(s) is displayed as
               label.
        Types: str
 
    ylim:
        Optional Argument.
        Specifies the range for ytick values.
        Types: tuple
 
    ytick_format:
        Optional Argument.
        Specifies whether to format tick values for y-axis or not.
        Types: str
 
    vmin:
        Optional Argument.
        Specifies the lower range of the color map. By default, the range
        is derived from data and color codes are assigned accordingly.
        Note:
            "vmin" Significant only for Geometry Plot.
        Types: int OR float
 
    vmax:
        Optional Argument.
        Specifies the upper range of the color map. By default, the range is
        derived from data and color codes are assigned accordingly.
        Note:
            "vmax" Significant only for Geometry Plot.
        For example:
            Assuming user wants to use colormap 'matter' and derive the colors for
            values which are in between 1 and 100.
            Note:
                colormap 'matter' starts with Pale Yellow and ends with Violet.
            * If "colormap_range" is not specified, then range is derived from
              existing values. Thus, colors are represented as below in the whole range:
              * 1 as Pale Yellow.
              * 100 as Violet.
            * If "colormap_range" is specified as -100 and 100, the value 1 is at middle of
              the specified range. Thus, colors are represented as below in the whole range:
              * -100 as Pale Yellow.
              * 1 as Orange.
              * 100 as Violet.
        Types: int OR float
 
    wiggle_fill:
        Optional Argument.
        Specifies whether to fill the wiggle area or not. By default, the right
        positive half of the wiggle is not filled. If specified as True, wiggle
        area is filled.
        Note:
            Applicable only for the wiggle plot.
        Default Value: False
        Types: bool
 
    wiggle_scale:
        Optional Argument.
        Specifies the scale of the wiggle. By default, the amplitude of wiggle is scaled
        relative to RMS of the first payload.  In certain cases, it can lead to excessively
        large wiggles. Use "wiggle_scale" to adjust the relative size of the wiggle.
        Note:
            Applicable only for the wiggle and mesh plots.
        Types: int OR float
 
    ignore_nulls:
        Optional Argument.
        Specifies whether to delete rows with null values or not present in 'x', 'y' and
        'scale' params.
        Default Value: False
        Types: bool
 
 
RAISES:
    TeradataMlException
 
EXAMPLES:
    >>> load_example_data("geodataframe", ["sample_shapes"])
    >>> shapes_df = GeoDataFrame("sample_shapes")
    >>> shapes_df
                                      points                     linestrings                        polygons                geom_collections                     geosequence
        skey
        1006    POINT (235.52 54.546 7.4564)  LINESTRING (1.35 3.6456 4.5,3.  POLYGON ((0 0 0,0 0 20,0 20 0,                            None                            None
        1007  MULTIPOINT (1 1,1 3,6 3,10 5,2  MULTILINESTRING ((1 1,1 3,6 3)  MULTIPOLYGON (((1 1,1 3,6 3,6                             None                            None
        1005                   POINT (1 3 5)  LINESTRING (1 3 6,3 0 6,6 0 1)  POLYGON ((0 0 0,0 0 20.435,0.0  GEOMETRYCOLLECTION (POINT (10                             None
        1004                POINT (10 20 30)  LINESTRING (10 20 30,40 50 60,  POLYGON ((0 0 0,0 10 20,20 20   GEOMETRYCOLLECTION (POINT (10                             None
        1003           POINT (235.52 54.546)  LINESTRING (1.35 3.6456,3.6756  POLYGON ((0.6 0.8,0.6 20.8,20.                            None                            None
        1001                   POINT (10 20)    LINESTRING (1 1,2 2,3 3,4 4)  POLYGON ((0 0,0 20,20 20,20 0,  GEOMETRYCOLLECTION (POINT (10   GEOSEQUENCE((10 20,30 40,50 60
        1002                     POINT (1 3)        LINESTRING (1 3,3 0,0 1)  POLYGON ((0 0,0 20,20 20,20 0,                            None  GEOSEQUENCE((10 10,15 15,-2 0)
        1009  MULTIPOINT (10 20 30,40 50 60,  MULTILINESTRING ((10 20 30,40   MULTIPOLYGON (((0 0 0,0 20 20,                            None                            None
        1008  MULTIPOINT (1.65 1.76,1.23 3.7  MULTILINESTRING ((1 3,3 0,0 1)  MULTIPOLYGON (((0 0,0 20,20 20                            None                            None
        1010  MULTIPOINT (10.345 20.32 30.6,  MULTILINESTRING ((1 3 6,3 0 6,  MULTIPOLYGON (((0 0 0,0 0 20,0                            None                            None
    >>>
    >>> load_example_data("geodataframe", ["us_population", "us_states_shapes"])
    >>> us_population
               location_type  population_year  population
    state_name
    Georgia            State             1930   2908506.0
    Georgia            State             1950   3444578.0
    Georgia            State             1960   3943116.0
    Georgia            State             1970   4589575.0
    Georgia            State             1990   6478216.0
    Georgia            State             2000   8186453.0
    Georgia            State             1980   5463105.0
    Georgia            State             1940   3123723.0
    Georgia            State             1920   2895832.0
    Georgia            State             1910   2609121.0
    >>> us_states_shapes = GeoDataFrame("us_states_shapes")
    >>> us_states_shapes
           state_name                     state_shape
    id
    NM     New Mexico  POLYGON ((472.45213 324.75551,
    VA       Virginia  POLYGON ((908.75086 270.98255,
    ND   North Dakota  POLYGON ((556.50879 73.847349,
    OK       Oklahoma  POLYGON ((609.50526 322.91131,
    WI      Wisconsin  POLYGON ((705.79187 134.80299,
    RI   Rhode Island  POLYGON ((946.50841 152.08022,
    HI         Hawaii  POLYGON ((416.34965 514.99923,
    KY       Kentucky  POLYGON ((693.17367 317.18459,
    WV  West Virginia  POLYGON ((836.73002 223.71281,
    NJ     New Jersey  POLYGON ((916.80709 207.30914,
    >>>
    >>> # Join shapes with population and filter only 1990 data.
    >>> population_data = us_states_shapes.join(us_population,
    ...                                         on=us_population.state_name == us_states_shapes.state_name,
    ...                                         lsuffix="us",
    ...                                         rsuffix="t2")
    >>> population_data = population_data.select(["us_state_name", "state_shape", "population_year", "population"])
    >>> type(population_data)
    teradataml.geospatial.geodataframe.GeoDataFrame
    >>>
 
    # Example 1: Generate the geometry plot to show the density of population
    #            across the US states in year 1990.
    >>> population_data_1990 = population_data[population_data.population_year == 1990]
    >>> population_data_1990
       us_state_name                     state_shape  population_year  population
    0     New Mexico  POLYGON ((472.45213 324.75551,             1990   1515069.0
    1         Hawaii  POLYGON ((416.34965 514.99923,             1990   1108229.0
    2       Kentucky  POLYGON ((693.17367 317.18459,             1990   3685296.0
    3     New Jersey  POLYGON ((916.80709 207.30914,             1990   7730188.0
    4   North Dakota  POLYGON ((556.50879 73.847349,             1990    638800.0
    5       Oklahoma  POLYGON ((609.50526 322.91131,             1990   3145585.0
    6  West Virginia  POLYGON ((836.73002 223.71281,             1990   1793477.0
    7      Wisconsin  POLYGON ((705.79187 134.80299,             1990   4891769.0
    8       Virginia  POLYGON ((908.75086 270.98255,             1990   6187358.0
    9   Rhode Island  POLYGON ((946.50841 152.08022,             1990   1003464.0
    >>>
    >>> # Define Figure.
    >>> from teradataml import Figure
    >>> figure = Figure(width=1500, height=862, heading="Geometry Plot")
    >>> figure.heading = "Geometry Plot"
    >>>
    >>> plot_1990 = population_data_1990.plot(y=population_data_1990.population,
    ...                                       cmap='rainbow',
    ...                                       figure=figure,
    ...                                       reverse_yaxis=True,
    ...                                       title="US 1990 Population",
    ...                                       xlabel="",
    ...                                       ylabel="")
    >>>
    >>> plot_1990.show()
    
    # Example 2: Plot a geometry plot for a single polygon to visualize the shape.
    # Note: X-axis is not significant in geometry plot. Y-axis can be a tuple,
    #       first element represents weight of geometry shape and second element
    #       represents the geometry column. Since color of geometry shape is generated
    #       based on first column and since the example is to plot a single polygon,
    #       the first element in tuple is not significant.
    >>> # Generate GeoDataFrame which has single Polygon.
    >>> single_polygon_df = shapes_df[shapes_df.skey==1004]
    >>> single_polygon_df.plot(y=(single_polygon_df.skey, single_polygon_df.polygons))
    
 
    # Example 3: Generate a bar plot on a GeoDataFrame.
    #     Note: The below example shows how the population of the United States
    #           changed from 1910 to 2020.
    >>> population_data.plot(x=population_data.population_year, y=population_data.population, kind="bar")
    
 
    # Example 4: Generate a subplot on a GeoDataFrame to show the rate of population increase over 4 decades.
    # Create DataFrames for population in the year 2020, 2010, 2000, 1990.
    >>> df_2020 = population_data[population_data.population_year == 2020]
    >>> df_2010 = population_data[population_data.population_year == 2010]
    >>> df_2000 = population_data[population_data.population_year == 2000]
    >>> df_1990 = population_data[population_data.population_year == 1990]
 
    # Define subplot.
    >>> fig, axes = subplots(nrows=2, ncols=2)
 
    >>> plot_population = df_1990.plot(y=(df_1990.population, df_1990.state_shape),
    ...                                   cmap='rainbow',
    ...                                   figure=fig,
    ...                                   ax=axis[0],
    ...                                   reverse_yaxis=True,
    ...                                   vmin=55036.0,
    ...                                   vmax=39538223.0,
    ...                                   heading="US Population growth over 4 decades",
    ...                                   title="US 1990 Population",
    ...                                   xlabel="",
    ...                                   yylabel="")
    >>> plot_population = df_2000.plot(y=(df_2000.population, df_2000.state_shape),
    ...                                   cmap='rainbow',
    ...                                   figure=fig,
    ...                                   ax=axis[1],
    ...                                   reverse_yaxis=True,
    ...                                   vmin=55036.0,
    ...                                   vmax=39538223.0,
    ...                                   heading="US Population growth over 4 decades",
    ...                                   title="US 2000 Population",
    ...                                   xlabel="",
    ...                                   ylabel="")
    >>> plot_population = df_2010.plot(x=df_2010.population_year,
    ...                                y=(df_2010.population, df_2010.state_shape),
    ...                                cmap='rainbow',
    ...                                figure=fig,
    ...                                ax=axis[2],
    ...                                reverse_yaxis=True,
    ...                                vmin=55036.0,
    ...                                vmax=39538223.0,
    ...                                heading="US Population growth over 4 decades",
    ...                                title="US 2010 Population",
    ...                                xlabel="",
    ...                                ylabel="",
    ...                                xtick_values_format="")
    >>> plot_population = df_2020.plot(x=df_2020.population_year,
    ...                                y=(df_2020.population, df_2020.state_shape),
    ...                                cmap='rainbow',
    ...                                figure=fig,
    ...                                ax=axis[3],
    ...                                reverse_yaxis=True,
    ...                                vmin=55036.0,
    ...                                vmax=39538223.0,
    ...                                heading="US Population growth over 4 decades",
    ...                                title="US 2020 Population",
    ...                                xlabel="",
    ...                                ylabel="",
    ...                                xtick_values_format="")
    >>> # Show the plot.
    >>> plot_population.show()