### `geopandas.read_file(filename, bbox=None, mask=None, columns=None, rows=None, engine=None, **kwargs)`

Return a GeoDataFrame from a file or URL.

Parameters
----------
filename : str, path object or file-like object
Either the absolute or relative path to the file or URL to
be opened, or any object with a read() method (such as an open file
or StringIO)
bbox : tuple | GeoDataFrame or GeoSeries | shapely Geometry, default None
Filter features by given bounding box, GeoSeries, GeoDataFrame or a shapely
geometry. With engine="fiona", CRS mis-matches are resolved if given a GeoSeries
or GeoDataFrame. With engine="pyogrio", bbox must be in the same CRS as the
dataset. Tuple is (minx, miny, maxx, maxy) to match the bounds property of
shapely geometry objects. Cannot be used with mask.
mask : dict | GeoDataFrame or GeoSeries | shapely Geometry, default None
Filter for features that intersect with the given dict-like geojson
geometry, GeoSeries, GeoDataFrame or shapely geometry.
CRS mis-matches are resolved if given a GeoSeries or GeoDataFrame.
Cannot be used with bbox. If multiple geometries are passed, this will
first union all geometries, which may be computationally expensive.
columns : list, optional
List of column names to import from the data source. Column names
must exactly match the names in the data source. To avoid reading
any columns (besides the geometry column), pass an empty list-like.
By default reads all columns.
rows : int or slice, default None
Load in specific rows by passing an integer (first `n` rows) or a
slice() object.
engine : str,  "pyogrio" or "fiona"
The underlying library that is used to read the file. Currently, the
supported options are "pyogrio" and "fiona". Defaults to "pyogrio" if
installed, otherwise tries "fiona". Engine can also be set globally
with the ``geopandas.options.io_engine`` option.
**kwargs :
Keyword args to be passed to the engine, and can be used to write
to multi-layer data, store data within archives (zip files), etc.
In case of the "pyogrio" engine, the keyword arguments are passed to
`pyogrio.read_dataframe`. In case of the "fiona" engine, the keyword
arguments are passed to fiona.open`. For more information on possible
keywords, type: ``import pyogrio; help(pyogrio.read_dataframe)``.


Examples
--------
> > > df = geopandas.read_file("nybb.shp")  # doctest: +SKIP

Specifying layer of GPKG:

> > > df = geopandas.read_file("file.gpkg", layer='cities')  # doctest: +SKIP

Reading only first 10 rows:

> > > df = geopandas.read_file("nybb.shp", rows=10)  # doctest: +SKIP

Reading only geometries intersecting ``mask``:

> > > df = geopandas.read_file("nybb.shp", mask=polygon)  # doctest: +SKIP

Reading only geometries intersecting ``bbox``:

> > > df = geopandas.read_file("nybb.shp", bbox=(0, 0, 10, 20))  # doctest: +SKIP

Returns
-------
:obj:`geopandas.GeoDataFrame` or :obj:`pandas.DataFrame` :
If `ignore_geometry=True` a :obj:`pandas.DataFrame` will be returned.

Notes
-----
The format drivers will attempt to detect the encoding of your data, but
may fail. In this case, the proper encoding can be specified explicitly
by using the encoding keyword parameter, e.g. ``encoding='utf-8'``.

For faster data reading with the default pyogrio engine when
pyarrow is installed, pass ``use_arrow=True`` as an argument. See the User
Guide page :doc:`../../user_guide/io` for details.

When specifying a URL, geopandas will check if the server supports reading
partial data and in that case pass the URL as is to the underlying engine,
which will then use the network file system handler of GDAL to read from
the URL. Otherwise geopandas will download the data from the URL and pass
all data in-memory to the underlying engine.
If you need more control over how the URL is read, you can specify the
GDAL virtual filesystem manually (e.g. ``/vsicurl/https://...``). See the
GDAL documentation on filesystems for more details
(https://gdal.org/user/virtual_file_systems.html#vsicurl-http-https-ftp-files-random-access).

---

### `geopandas.GeoDataFrame(data=None, *args, geometry: 'Any | None' = None, crs: 'Any | None' = None, **kwargs)`

A GeoDataFrame object is a pandas.DataFrame that has one or more columns
containing geometry.

In addition to the standard DataFrame constructor arguments,
GeoDataFrame also accepts the following keyword arguments:

Parameters
----------
crs : value (optional)
Coordinate Reference System of the geometry objects. Can be anything accepted by
:meth:`pyproj.CRS.from_user_input() <pyproj.crs.CRS.from_user_input>`,
such as an authority string (eg "EPSG:4326") or a WKT string.
geometry : str or array-like (optional)
Value to use as the active geometry column.
If str, treated as column name to use. If array-like, it will be
added as new column named 'geometry' on the GeoDataFrame and set as the
active geometry column.

    Note that if ``geometry`` is a (Geo)Series with a
    name, the name will not be used, a column named "geometry" will still be
    added. To preserve the name, you can use :meth:`~GeoDataFrame.rename_geometry`
    to update the geometry column name.

Examples
--------
Constructing GeoDataFrame from a dictionary.

> > > from shapely.geometry import Point
> > > d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]}
> > > gdf = geopandas.GeoDataFrame(d, crs="EPSG:4326")
> > > gdf
> > > col1 geometry
> > > 0 name1 POINT (1 2)
> > > 1 name2 POINT (2 1)

Notice that the inferred dtype of 'geometry' columns is geometry.

> > > gdf.dtypes
> > > col1 object
> > > geometry geometry
> > > dtype: object

Constructing GeoDataFrame from a pandas DataFrame with a column of WKT geometries:

> > > import pandas as pd
> > > d = {'col1': ['name1', 'name2'], 'wkt': ['POINT (1 2)', 'POINT (2 1)']}
> > > df = pd.DataFrame(d)
> > > gs = geopandas.GeoSeries.from_wkt(df['wkt'])
> > > gdf = geopandas.GeoDataFrame(df, geometry=gs, crs="EPSG:4326")
> > > gdf
> > > col1 wkt geometry
> > > 0 name1 POINT (1 2)  POINT (1 2)
> > > 1 name2 POINT (2 1)  POINT (2 1)

See Also
--------
GeoSeries : Series object designed to store shapely geometry objects

---

### `geopandas.GeoSeries(data=None, index=None, crs: 'Any | None' = None, **kwargs)`

A Series object designed to store shapely geometry objects.

Parameters
----------
data : array-like, dict, scalar value
The geometries to store in the GeoSeries.
index : array-like or Index
The index for the GeoSeries.
crs : value (optional)
Coordinate Reference System of the geometry objects. Can be anything accepted by
:meth:`pyproj.CRS.from_user_input() <pyproj.crs.CRS.from_user_input>`,
such as an authority string (eg "EPSG:4326") or a WKT string.

kwargs
Additional arguments passed to the Series constructor,
e.g. ``name``.

Examples
--------
> > > from shapely.geometry import Point
> > > s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)])
> > > s
> > > 0 POINT (1 1)
> > > 1 POINT (2 2)
> > > 2 POINT (3 3)
> > > dtype: geometry

> > > s = geopandas.GeoSeries(
> > > ...     [Point(1, 1), Point(2, 2), Point(3, 3)], crs="EPSG:3857"
> > > ... )
> > > s.crs # doctest: +SKIP
<Projected CRS: EPSG:3857>
> > > Name: WGS 84 / Pseudo-Mercator
> > > Axis Info [cartesian]:

- X[east]: Easting (metre)
- Y[north]: Northing (metre)
  Area of Use:
- name: World - 85░S to 85░N
- bounds: (-180.0, -85.06, 180.0, 85.06)
  Coordinate Operation:
- name: Popular Visualisation Pseudo-Mercator
- method: Popular Visualisation Pseudo Mercator
  Datum: World Geodetic System 1984
- Ellipsoid: WGS 84
- Prime Meridian: Greenwich

> > > s = geopandas.GeoSeries(
> > > ...    [Point(1, 1), Point(2, 2), Point(3, 3)], index=["a", "b", "c"], crs=4326
> > > ... )
> > > s
> > > a POINT (1 1)
> > > b POINT (2 2)
> > > c POINT (3 3)
> > > dtype: geometry

> > > s.crs
<Geographic 2D CRS: EPSG:4326>
> > > Name: WGS 84
> > > Axis Info [ellipsoidal]:

- Lat[north]: Geodetic latitude (degree)
- Lon[east]: Geodetic longitude (degree)
  Area of Use:
- name: World.
- bounds: (-180.0, -90.0, 180.0, 90.0)
  Datum: World Geodetic System 1984 ensemble
- Ellipsoid: WGS 84
- Prime Meridian: Greenwich

See Also
--------
GeoDataFrame
pandas.Series

---

###
`geopandas.GeoDataFrame.to_crs(self, crs: 'Any | None' = None, epsg: 'int | None' = None, inplace: 'bool' = False) -> 'GeoDataFrame | None'`

Transform geometries to a new coordinate reference system.

Transform all geometries in an active geometry column to a different coordinate
reference system. The ``crs`` attribute on the current GeoSeries must
be set. Either ``crs`` or ``epsg`` may be specified for output.

This method will transform all points in all objects. It has no notion
of projecting entire geometries. All segments joining points are
assumed to be lines in the current projection, not geodesics. Objects
crossing the dateline (or other projection boundary) will have
undesirable behavior.

Parameters
----------
crs : pyproj.CRS, optional if `epsg` is specified
The value can be anything accepted by
:meth:`pyproj.CRS.from_user_input() <pyproj.crs.CRS.from_user_input>`,
such as an authority string (eg "EPSG:4326") or a WKT string.
epsg : int, optional if `crs` is specified
EPSG code specifying output projection.
inplace : bool, optional, default: False
Whether to return a new GeoDataFrame or do the transformation in
place.

Returns
-------
GeoDataFrame

Examples
--------
> > > from shapely.geometry import Point
> > > d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]}
> > > gdf = geopandas.GeoDataFrame(d, crs=4326)
> > > gdf
> > > col1 geometry
> > > 0 name1 POINT (1 2)
> > > 1 name2 POINT (2 1)
> > > gdf.crs # doctest: +SKIP
<Geographic 2D CRS: EPSG:4326>
> > > Name: WGS 84
> > > Axis Info [ellipsoidal]:

- Lat[north]: Geodetic latitude (degree)
- Lon[east]: Geodetic longitude (degree)
  Area of Use:
- name: World
- bounds: (-180.0, -90.0, 180.0, 90.0)
  Datum: World Geodetic System 1984
- Ellipsoid: WGS 84
- Prime Meridian: Greenwich

> > > gdf = gdf.to_crs(3857)
> > > gdf
> > > col1 geometry
> > > 0 name1 POINT (111319.491 222684.209)
> > > 1 name2 POINT (222638.982 111325.143)
> > > gdf.crs # doctest: +SKIP
<Projected CRS: EPSG:3857>
> > > Name: WGS 84 / Pseudo-Mercator
> > > Axis Info [cartesian]:

- X[east]: Easting (metre)
- Y[north]: Northing (metre)
  Area of Use:
- name: World - 85░S to 85░N
- bounds: (-180.0, -85.06, 180.0, 85.06)
  Coordinate Operation:
- name: Popular Visualisation Pseudo-Mercator
- method: Popular Visualisation Pseudo Mercator
  Datum: World Geodetic System 1984
- Ellipsoid: WGS 84
- Prime Meridian: Greenwich

See Also
--------
GeoDataFrame.set_crs : assign CRS without re-projection

---

###
`geopandas.sjoin(left_df, right_df, how='inner', predicate='intersects', lsuffix='left', rsuffix='right', distance=None, on_attribute=None, **kwargs)`

Spatial join of two GeoDataFrames.

See the User Guide page :doc:`../../user_guide/mergingdata` for details.


Parameters
----------
left_df, right_df : GeoDataFrames
how : string, default 'inner'
The type of join:

    * 'left': use keys from left_df; retain only left_df geometry column
    * 'right': use keys from right_df; retain only right_df geometry column
    * 'inner': use intersection of keys from both dfs; retain only
      left_df geometry column

predicate : string, default 'intersects'
Binary predicate. Valid values are determined by the spatial index used.
You can check the valid values in left_df or right_df as
``left_df.sindex.valid_query_predicates`` or
``right_df.sindex.valid_query_predicates``
Replaces deprecated ``op`` parameter.
lsuffix : string, default 'left'
Suffix to apply to overlapping column names (left GeoDataFrame).
rsuffix : string, default 'right'
Suffix to apply to overlapping column names (right GeoDataFrame).
distance : number or array_like, optional
Distance(s) around each input geometry within which to query the tree
for the 'dwithin' predicate. If array_like, must be
one-dimesional with length equal to length of left GeoDataFrame.
Required if ``predicate='dwithin'``.
on_attribute : string, list or tuple
Column name(s) to join on as an additional join restriction on top
of the spatial predicate. These must be found in both DataFrames.
If set, observations are joined only if the predicate applies
and values in specified columns match.

Examples
--------
> > > import geodatasets
> > > chicago = geopandas.read_file(
> > > ... geodatasets.get_path("geoda.chicago_health")
> > > ... )
> > > groceries = geopandas.read_file(
> > > ... geodatasets.get_path("geoda.groceries")
> > > ... ).to_crs(chicago.crs)

> > > chicago.head()  # doctest: +SKIP
> > > ComAreaID ... geometry
> > > 0 35 ... POLYGON ((-87.60914 41.84469, -87.60915 41.844...
> > > 1 36 ... POLYGON ((-87.59215 41.81693, -87.59231 41.816...
> > > 2 37 ... POLYGON ((-87.62880 41.80189, -87.62879 41.801...
> > > 3 38 ... POLYGON ((-87.60671 41.81681, -87.60670 41.816...
> > > 4 39 ... POLYGON ((-87.59215 41.81693, -87.59215 41.816...
[5 rows x 87 columns]

> > > groceries.head()  # doctest: +SKIP
> > > OBJECTID Ycoord ... Category geometry
> > > 0 16 41.973266 ... NaN MULTIPOINT (-87.65661 41.97321)
> > > 1 18 41.696367 ... NaN MULTIPOINT (-87.68136 41.69713)
> > > 2 22 41.868634 ... NaN MULTIPOINT (-87.63918 41.86847)
> > > 3 23 41.877590 ... new MULTIPOINT (-87.65495 41.87783)
> > > 4 27 41.737696 ... NaN MULTIPOINT (-87.62715 41.73623)
[5 rows x 8 columns]

> > > groceries_w_communities = geopandas.sjoin(groceries, chicago)
> > > groceries_w_communities.head()  # doctest: +SKIP
> > > OBJECTID community geometry
> > > 0 16 UPTOWN MULTIPOINT ((-87.65661 41.97321))
> > > 1 18 MORGAN PARK MULTIPOINT ((-87.68136 41.69713))
> > > 2 22 NEAR WEST SIDE MULTIPOINT ((-87.63918 41.86847))
> > > 3 23 NEAR WEST SIDE MULTIPOINT ((-87.65495 41.87783))
> > > 4 27 CHATHAM MULTIPOINT ((-87.62715 41.73623))
[5 rows x 95 columns]

See Also
--------
overlay : overlay operation resulting in a new geometry
GeoDataFrame.sjoin : equivalent method

Notes
-----
Every operation in GeoPandas is planar, i.e. the potential third
dimension is not taken into account.

---

### `geopandas.overlay(df1, df2, how='intersection', keep_geom_type=None, make_valid=True)`

Perform spatial overlay between two GeoDataFrames.

Currently only supports data GeoDataFrames with uniform geometry types,
i.e. containing only (Multi)Polygons, or only (Multi)Points, or a
combination of (Multi)LineString and LinearRing shapes.
Implements several methods that are all effectively subsets of the union.

See the User Guide page :doc:`../../user_guide/set_operations` for details.

Parameters
----------
df1 : GeoDataFrame
df2 : GeoDataFrame
how : string
Method of spatial overlay: 'intersection', 'union',
'identity', 'symmetric_difference' or 'difference'.
keep_geom_type : bool
If True, return only geometries of the same geometry type as df1 has,
if False, return all resulting geometries. Default is None,
which will set keep_geom_type to True but warn upon dropping
geometries.
make_valid : bool, default True
If True, any invalid input geometries are corrected with a call to make_valid(),
if False, a `ValueError` is raised if any input geometries are invalid.

Returns
-------
df : GeoDataFrame
GeoDataFrame with new set of polygons and attributes
resulting from the overlay

Examples
--------
> > > from shapely.geometry import Polygon
> > > polys1 = geopandas.GeoSeries([Polygon([(0,0), (2,0), (2,2), (0,2)]),
> > > ... Polygon([(2,2), (4,2), (4,4), (2,4)])])
> > > polys2 = geopandas.GeoSeries([Polygon([(1,1), (3,1), (3,3), (1,3)]),
> > > ... Polygon([(3,3), (5,3), (5,5), (3,5)])])
> > > df1 = geopandas.GeoDataFrame({'geometry': polys1, 'df1_data':[1,2]})
> > > df2 = geopandas.GeoDataFrame({'geometry': polys2, 'df2_data':[1,2]})

> > > geopandas.overlay(df1, df2, how='union')
> > > df1_data df2_data geometry
> > > 0 1.0 1.0 POLYGON ((2 2, 2 1, 1 1, 1 2, 2 2))
> > > 1 2.0 1.0 POLYGON ((2 2, 2 3, 3 3, 3 2, 2 2))
> > > 2 2.0 2.0 POLYGON ((4 4, 4 3, 3 3, 3 4, 4 4))
> > > 3 1.0 NaN POLYGON ((2 0, 0 0, 0 2, 1 2, 1 1, 2 1, 2 0))
> > > 4 2.0 NaN MULTIPOLYGON (((3 4, 3 3, 2 3, 2 4, 3 4)), ((4...
> > > 5 NaN 1.0 MULTIPOLYGON (((2 3, 2 2, 1 2, 1 3, 2 3)), ((3...
> > > 6 NaN 2.0 POLYGON ((3 5, 5 5, 5 3, 4 3, 4 4, 3 4, 3 5))

> > > geopandas.overlay(df1, df2, how='intersection')
> > > df1_data df2_data geometry
> > > 0 1 1 POLYGON ((2 2, 2 1, 1 1, 1 2, 2 2))
> > > 1 2 1 POLYGON ((2 2, 2 3, 3 3, 3 2, 2 2))
> > > 2 2 2 POLYGON ((4 4, 4 3, 3 3, 3 4, 4 4))

> > > geopandas.overlay(df1, df2, how='symmetric_difference')
> > > df1_data df2_data geometry
> > > 0 1.0 NaN POLYGON ((2 0, 0 0, 0 2, 1 2, 1 1, 2 1, 2 0))
> > > 1 2.0 NaN MULTIPOLYGON (((3 4, 3 3, 2 3, 2 4, 3 4)), ((4...
> > > 2 NaN 1.0 MULTIPOLYGON (((2 3, 2 2, 1 2, 1 3, 2 3)), ((3...
> > > 3 NaN 2.0 POLYGON ((3 5, 5 5, 5 3, 4 3, 4 4, 3 4, 3 5))

> > > geopandas.overlay(df1, df2, how='difference')
> > > geometry df1_data
> > > 0 POLYGON ((2 0, 0 0, 0 2, 1 2, 1 1, 2 1, 2 0))         1
> > > 1 MULTIPOLYGON (((3 4, 3 3, 2 3, 2 4, 3 4)), ((4... 2

> > > geopandas.overlay(df1, df2, how='identity')
> > > df1_data df2_data geometry
> > > 0 1 1.0 POLYGON ((2 2, 2 1, 1 1, 1 2, 2 2))
> > > 1 2 1.0 POLYGON ((2 2, 2 3, 3 3, 3 2, 2 2))
> > > 2 2 2.0 POLYGON ((4 4, 4 3, 3 3, 3 4, 4 4))
> > > 3 1 NaN POLYGON ((2 0, 0 0, 0 2, 1 2, 1 1, 2 1, 2 0))
> > > 4 2 NaN MULTIPOLYGON (((3 4, 3 3, 2 3, 2 4, 3 4)), ((4...

See Also
--------
sjoin : spatial join
GeoDataFrame.overlay : equivalent method

Notes
-----
Every operation in GeoPandas is planar, i.e. the potential third
dimension is not taken into account.

---

###
`geopandas.GeoSeries.buffer(self, distance, resolution=16, cap_style='round', join_style='round', mitre_limit=5.0, single_sided=False, **kwargs)`

Return a ``GeoSeries`` of geometries representing all points within
a given ``distance`` of each geometric object.

Computes the buffer of a geometry for positive and negative buffer distance.

The buffer of a geometry is defined as the Minkowski sum (or difference, for
negative distance) of the geometry with a circle with radius equal to the
absolute value of the buffer distance.

The buffer operation always returns a polygonal result. The negative or
zero-distance buffer of lines and points is always empty.

Parameters
----------
distance : float, np.array, pd.Series
The radius of the buffer in the Minkowski sum (or difference). If np.array
or pd.Series are used then it must have same length as the GeoSeries.
resolution : int (optional, default 16)
The resolution of the buffer around each vertex. Specifies the number of
linear segments in a quarter circle in the approximation of circular arcs.
cap_style : {'round', 'square', 'flat'}, default 'round'
Specifies the shape of buffered line endings. ``'round'`` results in
circular line endings (see ``resolution``). Both ``'square'`` and ``'flat'``
result in rectangular line endings, ``'flat'`` will end at the original
vertex, while ``'square'`` involves adding the buffer width.
join_style : {'round', 'mitre', 'bevel'}, default 'round'
Specifies the shape of buffered line midpoints. ``'round'`` results in
rounded shapes. ``'bevel'`` results in a beveled edge that touches the
original vertex. ``'mitre'`` results in a single vertex that is beveled
depending on the ``mitre_limit`` parameter.
mitre_limit : float, default 5.0
Crops of ``'mitre'``-style joins if the point is displaced from the
buffered vertex by more than this limit.
single_sided : bool, default False
Only buffer at one side of the geometry.

Examples
--------
> > > from shapely.geometry import Point, LineString, Polygon
> > > s = geopandas.GeoSeries(
> > > ...     [
> > > ... Point(0, 0),
> > > ... LineString([(1, -1), (1, 0), (2, 0), (2, 1)]),
> > > ... Polygon([(3, -1), (4, 0), (3, 1)]),
> > > ...     ]
> > > ... )
> > > s
> > > 0 POINT (0 0)
> > > 1 LINESTRING (1 -1, 1 0, 2 0, 2 1)
> > > 2 POLYGON ((3 -1, 4 0, 3 1, 3 -1))
> > > dtype: geometry

> > > s.buffer(0.2)
> > > 0 POLYGON ((0.2 0, 0.19904 -0.0196, 0.19616 -0.0...
> > > 1 POLYGON ((0.8 0, 0.80096 0.0196, 0.80384 0.039...
> > > 2 POLYGON ((2.8 -1, 2.8 1, 2.80096 1.0196, 2.803...
> > > dtype: geometry

``Further specification as ``join_style`` and ``cap_style`` are shown in the
following illustration:

.. plot:: _static/code/buffer.py

---

### `geopandas.GeoSeries.centroid`

Return a ``GeoSeries`` of points representing the centroid of each
geometry.

Note that centroid does not have to be on or within original geometry.

Examples
--------
> > > from shapely.geometry import Polygon, LineString, Point
> > > s = geopandas.GeoSeries(
> > > ...     [
> > > ... Polygon([(0, 0), (1, 1), (0, 1)]),
> > > ... LineString([(0, 0), (1, 1), (1, 0)]),
> > > ... Point(0, 0),
> > > ...     ]
> > > ... )
> > > s
> > > 0 POLYGON ((0 0, 1 1, 0 1, 0 0))
> > > 1 LINESTRING (0 0, 1 1, 1 0)
> > > 2 POINT (0 0)
> > > dtype: geometry

> > > s.centroid
> > > 0 POINT (0.33333 0.66667)
> > > 1 POINT (0.70711 0.5)
> > > 2 POINT (0 0)
> > > dtype: geometry

See Also
--------
GeoSeries.representative_point : point guaranteed to be within each geometry

---

###
`geopandas.GeoDataFrame.dissolve(self, by: 'str | None' = None, aggfunc='first', as_index: 'bool' = True, level=None, sort: 'bool' = True, observed: 'bool' = False, dropna: 'bool' = True, method: "Literal['unary', 'coverage', 'disjoint_subset']" = 'unary', grid_size: 'float | None' = None, **kwargs) -> 'GeoDataFrame'`

Dissolve geometries within `groupby` into single observation.
This is accomplished by applying the `union_all` method
to all geometries within a groupself.

Observations associated with each `groupby` group will be aggregated
using the `aggfunc`.

Parameters
----------
by : str or list-like, default None
Column(s) whose values define the groups to be dissolved. If None,
the entire GeoDataFrame is considered as a single group. If a list-like
object is provided, the values in the list are treated as categorical
labels, and polygons will be combined based on the equality of
these categorical labels.
aggfunc : function or string, default "first"
Aggregation function for manipulation of data associated
with each group. Passed to pandas `groupby.agg` method.
Accepted combinations are:

    - function
    - string function name
    - list of functions and/or function names, e.g. [np.sum, 'mean']
    - dict of axis labels -> functions, function names or list of such.

as_index : boolean, default True
If true, groupby columns become index of result.
level : int or str or sequence of int or sequence of str, default None
If the axis is a MultiIndex (hierarchical), group by a
particular level or levels.
sort : bool, default True
Sort group keys. Get better performance by turning this off.
Note this does not influence the order of observations within
each group. Groupby preserves the order of rows within each group.
observed : bool, default False
This only applies if any of the groupers are Categoricals.
If True: only show observed values for categorical groupers.
If False: show all values for categorical groupers.
dropna : bool, default True
If True, and if group keys contain NA values, NA values
together with row/column will be dropped. If False, NA
values will also be treated as the key in groups.
method : str (default ``"unary"``)
The method to use for the union. Options are:

    * ``"unary"``: use the unary union algorithm. This option is the most robust
      but can be slow for large numbers of geometries (default).
    * ``"coverage"``: use the coverage union algorithm. This option is optimized
      for non-overlapping polygons and can be significantly faster than the
      unary union algorithm. However, it can produce invalid geometries if the
      polygons overlap.
    * ``"disjoint_subset:``: use the disjoint subset union algorithm. This
      option is optimized for inputs that can be divided into subsets that do
      not intersect. If there is only one such subset, performance can be
      expected to be worse than ``"unary"``.  Requires Shapely >= 2.1.

grid_size : float, default None
When grid size is specified, a fixed-precision space is used to perform the
union operations. This can be useful when unioning geometries that are not
perfectly snapped or to avoid geometries not being unioned because of
`robustness issues <https://libgeos.org/usage/faq/#why-doesnt-a-computed-point-lie-exactly-on-a-line>`_.
The inputs are first snapped to a grid of the given size. When a line
segment of a geometry is within tolerance off a vertex of another geometry,
this vertex will be inserted in the line segment. Finally, the result
vertices are computed on the same grid. Is only supported for ``method``
``"unary"``. If None, the highest precision of the inputs will be used.
Defaults to None.

    .. versionadded:: 1.1.0

**kwargs :
Keyword arguments to be passed to the pandas `DataFrameGroupby.agg` method
which is used by `dissolve`. In particular, `numeric_only` may be
supplied, which will be required in pandas 2.0 for certain aggfuncs.

    .. versionadded:: 0.13.0

Returns
-------
GeoDataFrame

Examples
--------
> > > from shapely.geometry import Point
> > > d = {
> > > ...     "col1": ["name1", "name2", "name1"],
> > > ...     "geometry": [Point(1, 2), Point(2, 1), Point(0, 1)],
> > > ... }
> > > gdf = geopandas.GeoDataFrame(d, crs=4326)
> > > gdf
> > > col1 geometry
> > > 0 name1 POINT (1 2)
> > > 1 name2 POINT (2 1)
> > > 2 name1 POINT (0 1)

> > > dissolved = gdf.dissolve('col1')
> > > dissolved # doctest: +SKIP
> > > geometry
> > > col1
> > > name1 MULTIPOINT ((0 1), (1 2))
> > > name2 POINT (2 1)

See Also
--------
GeoDataFrame.explode : explode multi-part geometries into single geometries

---

### `geopandas.GeoDataFrame.plot(data: 'Series | DataFrame') -> 'None'`

Plot a GeoDataFrame.

Generate a plot of a GeoDataFrame with matplotlib. If a
column is specified, the plot coloring will be based on values
in that column.

Parameters
----------
column : str, np.array, pd.Series, pd.Index (default None)
The name of the dataframe column, np.array, pd.Series, or pd.Index
to be plotted. If np.array, pd.Series, or pd.Index are used then it
must have same length as dataframe. Values are used to color the plot.
Ignored if `color` is also set.
kind: str
The kind of plots to produce. The default is to create a map ("geo").
Other supported kinds of plots from pandas:

    - 'line' : line plot
    - 'bar' : vertical bar plot
    - 'barh' : horizontal bar plot
    - 'hist' : histogram
    - 'box' : BoxPlot
    - 'kde' : Kernel Density Estimation plot
    - 'density' : same as 'kde'
    - 'area' : area plot
    - 'pie' : pie plot
    - 'scatter' : scatter plot
    - 'hexbin' : hexbin plot.

cmap : str (default None)
The name of a colormap recognized by matplotlib.
color : str, np.array, pd.Series (default None)
If specified, all objects will be colored uniformly.
ax : matplotlib.pyplot.Artist (default None)
axes on which to draw the plot
cax : matplotlib.pyplot Artist (default None)
axes on which to draw the legend in case of color map.
categorical : bool (default False)
If False, cmap will reflect numerical values of the
column being plotted. For non-numerical columns, this
will be set to True.
legend : bool (default False)
Plot a legend. Ignored if no `column` is given, or if `color` is given.
scheme : str (default None)
Name of a choropleth classification scheme (requires mapclassify).
A mapclassify.MapClassifier object will be used
under the hood. Supported are all schemes provided by mapclassify (e.g.
'BoxPlot', 'EqualInterval', 'FisherJenks', 'FisherJenksSampled',
'HeadTailBreaks', 'JenksCaspall', 'JenksCaspallForced',
'JenksCaspallSampled', 'MaxP', 'MaximumBreaks',
'NaturalBreaks', 'Quantiles', 'Percentiles', 'StdMean',
'UserDefined'). Arguments can be passed in classification_kwds.
k : int (default 5)
Number of classes (ignored if scheme is None)
vmin : None or float (default None)
Minimum value of cmap. If None, the minimum data value
in the column to be plotted is used.
vmax : None or float (default None)
Maximum value of cmap. If None, the maximum data value
in the column to be plotted is used.
markersize : str or float or sequence (default None)
Only applies to point geometries within a frame.
If a str, will use the values in the column of the frame specified
by markersize to set the size of markers. Otherwise can be a value
to apply to all points, or a sequence of the same length as the
number of points.
figsize : tuple of integers (default None)
Size of the resulting matplotlib.figure.Figure. If the argument
axes is given explicitly, figsize is ignored.
legend_kwds : dict (default None)
Keyword arguments to pass to :func:`matplotlib.pyplot.legend` or
:func:`matplotlib.pyplot.colorbar`.
Additional accepted keywords when `scheme` is specified:

    fmt : string
        A formatting specification for the bin edges of the classes in the
        legend. For example, to have no decimals: ``{"fmt": "{:.0f}"}``.
    labels : list-like
        A list of legend labels to override the auto-generated labels.
        Needs to have the same number of elements as the number of
        classes (`k`).
    interval : boolean (default False)
        An option to control brackets from mapclassify legend.
        If True, open/closed interval brackets are shown in the legend.

categories : list-like
Ordered list-like object of categories to be used for categorical plot.
classification_kwds : dict (default None)
Keyword arguments to pass to mapclassify
missing_kwds : dict (default None)
Keyword arguments specifying color options (as style_kwds)
to be passed on to geometries with missing values in addition to
or overwriting other style kwds. If None, geometries with missing
values are not plotted.
aspect : 'auto', 'equal', None or float (default 'auto')
Set aspect of axis. If 'auto', the default aspect for map plots is 'equal'; if
however data are not projected (coordinates are long/lat), the aspect is by
default set to 1/cos(df_y * pi/180) with df_y the y coordinate of the middle of
the GeoDataFrame (the mean of the y range of bounding box) so that a long/lat
square appears square in the middle of the plot. This implies an
Equirectangular projection. If None, the aspect of `ax` won't be changed. It can
also be set manually (float) as the ratio of y-unit to x-unit.
autolim : bool (default True)
Update axes data limits to contain the new geometries.
**style_kwds : dict
Style options to be passed on to the actual plot function, such
as ``edgecolor``, ``facecolor``, ``linewidth``, ``markersize``,
``alpha``.

Returns
-------
ax : matplotlib axes instance

Examples
--------
> > > import geodatasets
> > > df = geopandas.read_file(geodatasets.get_path("nybb"))
> > > df.head()  # doctest: +SKIP
> > > BoroCode ... geometry
> > > 0 5 ... MULTIPOLYGON (((970217.022 145643.332, 970227....
> > > 1 4 ... MULTIPOLYGON (((1029606.077 156073.814, 102957...
> > > 2 3 ... MULTIPOLYGON (((1021176.479 151374.797, 102100...
> > > 3 1 ... MULTIPOLYGON (((981219.056 188655.316, 980940....
> > > 4 2 ... MULTIPOLYGON (((1012821.806 229228.265, 101278...

> > > df.plot("BoroName", cmap="Set1")  # doctest: +SKIP

See the User Guide page :doc:`../../user_guide/mapping` for details.

---
