Geopandas

Small bug-fix release:

- Fix regression (RecursionError) in reshape methods such as ``unstack()``
and ``pivot()`` involving MultiIndex, or GeoDataFrame construction with
MultiIndex (2486).
- Fix regression in ``GeoDataFrame.explode()`` with non-default
geometry column name.
- Fix regression in ``apply()`` causing row-wise all nan float columns to be
casted to GeometryDtype (2482).
- Fix a crash in datetime column reading where the file contains mixed timezone
offsets (2479). These will be read as UTC localized values.
- Fix a crash in datetime column reading where the file contains datetimes
outside the range supported by [ns] precision (2505).
- Fix regression in passing the Parquet or Feather format ``version`` in
``to_parquet`` and ``to_feather``. As a result, the ``version`` parameter
for the ``to_parquet`` and ``to_feather`` methods has been replaced with
``schema_version``. ``version`` will be passed directly to underlying
feather or parquet writer. ``version`` will only be used to set
``schema_version`` if ``version`` is one of 0.1.0 or 0.4.0 (2496).

----------------------------

Highlights of this release:

- The ``geopandas.read_file()`` and `GeoDataFrame.to_file()` methods to read
and write GIS file formats can now optionally use the
[pyogrio](https://github.com/geopandas/pyogrio/) package under the hood
through the ``engine="pyogrio"`` keyword. The pyogrio package implements
vectorized IO for GDAL/OGR vector data sources, and is faster compared to
the ``fiona``-based engine (2225).
- GeoParquet support updated to implement
[v0.4.0](https://github.com/opengeospatial/geoparquet/releases/tag/v0.4.0) of the
OpenGeospatial/GeoParquet specification (2441). Backwards compatibility with v0.1.0 of
the metadata spec (implemented in the previous releases of GeoPandas) is guaranteed,
and reading and writing Parquet and Feather files will no longer produce a ``UserWarning``
(2327).

New features and improvements:

- Improved handling of GeoDataFrame when the active geometry column is
lost from the GeoDataFrame. Previously, square bracket indexing ``gdf[[...]]`` returned
a GeoDataFrame when the active geometry column was retained and a DataFrame was
returned otherwise. Other pandas indexing methods (``loc``, ``iloc``, etc) did not follow
the same rules. The new behaviour for all indexing/reshaping operations is now as
follows (2329, 2060):
- If operations produce a ``DataFrame`` containing the active geometry column, a
GeoDataFrame is returned
- If operations produce a ``DataFrame`` containing ``GeometryDtype`` columns, but not the
active geometry column, a ``GeoDataFrame`` is returned, where the active geometry
column is set to ``None`` (set the new geometry column with ``set_geometry()``)
- If operations produce a ``DataFrame`` containing no ``GeometryDtype`` columns, a
``DataFrame`` is returned (this can be upcast again by calling ``set_geometry()`` or the
``GeoDataFrame`` constructor)
- If operations produce a ``Series`` of ``GeometryDtype``, a ``GeoSeries`` is returned,
otherwise ``Series`` is returned.
- Error messages for having an invalid geometry column
have been improved, indicating the name of the last valid active geometry column set
and whether other geometry columns can be promoted to the active geometry column
(2329).

- Datetime fields are now read and written correctly for GIS formats which support them
(e.g. GPKG, GeoJSON) with fiona 1.8.14 or higher. Previously, datetimes were read as
strings (2202).
- ``folium.Map`` keyword arguments can now be specified as the ``map_kwds`` argument to
``GeoDataFrame.explore()`` method (2315).
- Add a new parameter ``style_function`` to ``GeoDataFrame.explore()`` to enable plot styling
based on GeoJSON properties (2377).
- It is now possible to write an empty ``GeoDataFrame`` to a file for supported formats
(2240). Attempting to do so will now emit a ``UserWarning`` instead of a ``ValueError``.
- Fast rectangle clipping has been exposed as ``GeoSeries/GeoDataFrame.clip_by_rect()``
(1928).
- The ``mask`` parameter of ``GeoSeries/GeoDataFrame.clip()`` now accepts a rectangular mask
as a list-like to perform fast rectangle clipping using the new
``GeoSeries/GeoDataFrame.clip_by_rect()`` (2414).
- Bundled demo dataset ``naturalearth_lowres`` has been updated to version 5.0.1 of the
source, with field ``ISO_A3`` manually corrected for some cases (2418).

Deprecations and compatibility notes:

- The active development branch of geopandas on GitHub has been renamed from master to
main (2277).
- Deprecated methods ``GeometryArray.equals_exact()`` and ``GeometryArray.almost_equals()``
have been removed. They should
be replaced with ``GeometryArray.geom_equals_exact()`` and
``GeometryArray.geom_almost_equals()`` respectively (2267).
- Deprecated CRS functions ``explicit_crs_from_epsg()``, ``epsg_from_crs()`` and
``get_epsg_file_contents()`` were removed (2340).
- Warning about the behaviour change to ``GeoSeries.isna()`` with empty
geometries present has been removed (2349).
- Specifying a CRS in the ``GeoDataFrame/GeoSeries`` constructor which contradicted the
underlying ``GeometryArray`` now raises a ``ValueError`` (2100).
- Specifying a CRS in the ``GeoDataFrame`` constructor when no geometry column is provided
and calling ``GeoDataFrame. set_crs`` on a ``GeoDataFrame`` without an active geometry
column now raise a ``ValueError`` (2100)
- Passing non-geometry data to the``GeoSeries`` constructor is now fully deprecated and
will raise a ``TypeError`` (2314). Previously, a ``pandas.Series`` was returned for
non-geometry data.
- Deprecated ``GeoSeries/GeoDataFrame`` set operations ``__xor__()``,
``__or__()``, ``__and__()`` and ``__sub__()``, ``geopandas.io.file.read_file``/``to_file`` and
``geopandas.io.sql.read_postgis`` now emit ``FutureWarning`` instead of
``DeprecationWarning`` and will be completely removed in a future release.
- Accessing the ``crs`` of a ``GeoDataFrame`` without active geometry column is deprecated and will be removed in GeoPandas 0.12 (2373).

Bug fixes:

- ``GeoSeries.to_frame`` now creates a ``GeoDataFrame`` with the geometry column name set
correctly (2296)
- Fix pickle files created with pygeos installed can not being readable when pygeos is
not installed (2237).
- Fixed ``UnboundLocalError`` in ``GeoDataFrame.plot()`` using ``legend=True`` and
``missing_kwds`` (2281).
- Fix ``explode()`` incorrectly relating index to columns, including where the input index
is not unique (2292)
- Fix ``GeoSeries.[xyz]`` raising an ``IndexError`` when the underlying GeoSeries contains
empty points (2335). Rows corresponding to empty points now contain ``np.nan``.
- Fix ``GeoDataFrame.iloc`` raising a ``TypeError`` when indexing a ``GeoDataFrame`` with only
a single column of ``GeometryDtype`` (1970).
- Fix ``GeoDataFrame.iterfeatures()`` not returning features with the same field order as
``GeoDataFrame.columns`` (2396).
- Fix ``GeoDataFrame.from_features()`` to support reading GeoJSON with null properties
(2243).
- Fix ``GeoDataFrame.to_parquet()`` not intercepting ``engine`` keyword argument, breaking
consistency with pandas (2227)
- Fix ``GeoDataFrame.explore()`` producing an error when ``column`` is of boolean dtype
(2403).
- Fix an issue where ``GeoDataFrame.to_postgis()`` output the wrong SRID for ESRI
authority CRS (2414).
- Fix ``GeoDataFrame.from_dict/from_features`` classmethods using ``GeoDataFrame`` rather
than ``cls`` as the constructor.
- Fix ``GeoDataFrame.plot()`` producing incorrect colors with mixed geometry types when
``colors`` keyword is provided. (2420)

Notes on (optional) dependencies:

- GeoPandas 0.11 drops support for Python 3.7 and pandas 0.25 (the minimum supported
pandas version is now 1.0.5). Further, the minimum required versions for the listed
dependencies have now changed to shapely 1.7, fiona 1.8.13.post1, pyproj 2.6.1.post1,
matplotlib 3.2, mapclassify 2.4.0 (2358, 2391)

---------------------------------

Small bug-fix release:

- Fix regression in ``overlay()`` in case no geometries are intersecting (but
have overlapping total bounds) (2172).
- Fix regression in ``overlay()`` with ``keep_geom_type=True`` in case the
overlay of two geometries in a GeometryCollection with other geometry types
(2177).
- Fix ``overlay()`` to honor the ``keep_geom_type`` keyword for the
``op="differnce"`` case (2164).
- Fix regression in ``plot()`` with a mapclassify ``scheme`` in case the
formatted legend labels have duplicates (2166).
- Fix a bug in the ``explore()`` method ignoring the ``vmin`` and ``vmax`` keywords
in case they are set to 0 (2175).
- Fix ``unary_union`` to correctly handle a GeoSeries with missing values (2181).
- Avoid internal deprecation warning in ``clip()`` (2179).

--------------------------------

Small bug-fix release:

- Fix regression in ``overlay()`` with non-overlapping geometries and a
non-default ``how`` (i.e. not "intersection") (2157).

--------------------------------

Highlights of this release:

- A new ``sjoin_nearest()`` method to join based on proximity, with the
ability to set a maximum search radius (1865). In addition, the ``sindex``
attribute gained a new method for a "nearest" spatial index query (1865,
2053).
- A new ``explore()`` method on GeoDataFrame and GeoSeries with native support
for interactive visualization based on folium / leaflet.js (1953)
- The ``geopandas.sjoin()``/``overlay()``/``clip()`` functions are now also
available as methods on the GeoDataFrame (2141, 1984, 2150).

New features and improvements:

- Add support for pandas' ``value_counts()`` method for geometry dtype (2047).
- The ``explode()`` method has a new ``ignore_index`` keyword (consistent with
pandas' explode method) to reset the index in the result, and a new
``index_parts`` keywords to control whether a cumulative count indexing the
parts of the exploded multi-geometries should be added (1871).
- ``points_from_xy()`` is now available as a GeoSeries method ``from_xy`` (1936).
- The ``to_file()`` method will now attempt to detect the driver (if not
specified) based on the extension of the provided filename, instead of
defaulting to ESRI Shapefile (1609).
- Support for the ``storage_options`` keyword in ``read_parquet()`` for
specifying filesystem-specific options (e.g. for S3) based on fsspec (2107).
- The read/write functions now support ``~`` (user home directory) expansion (1876).
- Support the ``convert_dtypes()`` method from pandas to preserve the
GeoDataFrame class (2115).
- Support WKB values in the hex format in ``GeoSeries.from_wkb()`` (2106).
- Update the ``estimate_utm_crs()`` method to handle crossing the antimeridian
with pyproj 3.1+ (2049).
- Improved heuristic to decide how many decimals to show in the repr based on
whether the CRS is projected or geographic (1895).
- Switched the default for ``geocode()`` from GeoCode.Farm to the Photon
geocoding API (<https://photon.komoot.io>) (#2007).

Deprecations and compatibility notes:

- The ``op=`` keyword of ``sjoin()`` to indicate which spatial predicate to use
for joining is being deprecated and renamed in favor of a new ``predicate=``
keyword (1626).
- The ``cascaded_union`` attribute is deprecated, use ``unary_union`` instead (2074).
- Constructing a GeoDataFrame with a duplicated "geometry" column is now
disallowed. This can also raise an error in the ``pd.concat(.., axis=1)``
function if this results in duplicated active geometry columns (2046).
- The ``explode()`` method currently returns a GeoSeries/GeoDataFrame with a
MultiIndex, with an additional level with indices of the parts of the
exploded multi-geometries. For consistency with pandas, this will change in
the future and the new ``index_parts`` keyword is added to control this.

Bug fixes:

- Fix in the ``clip()`` function to correctly clip MultiPoints instead of
leaving them intact when partly outside of the clip bounds (2148).
- Fix ``GeoSeries.isna()`` to correctly return a boolean Series in case of an
empty GeoSeries (2073).
- Fix the GeoDataFrame constructor to preserve the geometry name when the
argument is already a GeoDataFrame object (i.e. ``GeoDataFrame(gdf)``) (2138).
- Fix loss of the values' CRS when setting those values as a column
(``GeoDataFrame.__setitem__``) (1963)
- Fix in ``GeoDataFrame.apply()`` to preserve the active geometry column name
(1955).
- Fix in ``sjoin()`` to not ignore the suffixes in case of a right-join
(``how="right``) (2065).
- Fix ``GeoDataFrame.explode()`` with a MultiIndex (1945).
- Fix the handling of missing values in ``to/from_wkb`` and ``to_from_wkt`` (1891).
- Fix ``to_file()`` and ``to_json()`` when DataFrame has duplicate columns to
raise an error (1900).
- Fix bug in the colors shown with user-defined classification scheme (2019).
- Fix handling of the ``path_effects`` keyword in ``plot()`` (2127).
- Fix ``GeoDataFrame.explode()`` to preserve ``attrs`` (1935)

Notes on (optional) dependencies:

- GeoPandas 0.10.0 dropped support for Python 3.6 and pandas 0.24. Further,
the minimum required versions are numpy 1.18, shapely 1.6, fiona 1.8,
matplotlib 3.1 and pyproj 2.2.
- Plotting with a classification schema now requires mapclassify version >=
2.4 (1737).
- Compatibility fixes for the latest numpy in combination with Shapely 1.7 (2072)
- Compatibility fixes for the upcoming Shapely 1.8 (2087).
- Compatibility fixes for the latest PyGEOS (1872, 2014) and matplotlib
(colorbar issue, 2066).

---------------------------------

Many documentation improvements and a restyled and restructured website with
a new logo (1564, 1579, 1617, 1668, 1731, 1750, 1757, 1759).

New features and improvements:

- The ``geopandas.read_file`` function now accepts more general
file-like objects (e.g. ``fsspec`` open file objects). It will now also
automatically recognize zipped files (1535).
- The ``GeoDataFrame.plot()`` method now provides access to the pandas plotting
functionality for the non-geometry columns, either using the ``kind`` keyword
or the accessor method (e.g. ``gdf.plot(kind="bar")`` or ``gdf.plot.bar()``)
(1465).
- New ``from_wkt()``, ``from_wkb()``, ``to_wkt()``, ``to_wkb()`` methods for
GeoSeries to construct a GeoSeries from geometries in WKT or WKB
representation, or to convert a GeoSeries to a pandas Seriew with WKT or WKB
values (1710).
- New ``GeoSeries.z`` attribute to access the z-coordinates of Point geometries
(similar to the existing ``.x`` and ``.y`` attributes) (1773).
- The ``to_crs()`` method now handles missing values (1618).
- Support for pandas' new ``.attrs`` functionality (1658).
- The ``dissolve()`` method now allows dissolving by no column (``by=None``) to
create a union of all geometries (single-row GeoDataFrame) (1568).
- New ``estimate_utm_crs()`` method on GeoSeries/GeoDataFrame to determine the
UTM CRS based on the bounds (1646).
- ``GeoDataFrame.from_dict()`` now accepts ``geometry`` and ``crs`` keywords
(1619).
- ``GeoDataFrame.to_postgis()`` and ``geopandas.read_postgis()`` now supports
both sqlalchemy engine and connection objects (1638).
- The ``GeoDataFrame.explode()`` method now allows exploding based on a
non-geometry column, using the pandas implementation (1720).
- Performance improvement in ``GeoDataFrame/GeoSeries.explode()`` when using
the PyGEOS backend (1693).
- The binary operation and predicate methods (eg ``intersection()``,
``intersects()``) have a new ``align`` keyword which allows optionally not
aligning on the index before performing the operation with ``align=False``
(1668).
- The ``GeoDataFrame.dissolve()`` method now supports all relevant keywords of
``groupby()``, i.e. the ``level``, ``sort``, ``observed`` and ``dropna`` keywords
(1845).
- The ``geopandas.overlay()`` function now accepts ``make_valid=False`` to skip
the step to ensure the input geometries are valid using ``buffer(0)`` (1802).
- The ``GeoDataFrame.to_json()`` method gained a ``drop_id`` keyword to
optionally not write the GeoDataFrame's index as the "id" field in the
resulting JSON (1637).
- A new ``aspect`` keyword in the plotting methods to optionally allow retaining
the original aspect (1512)
- A new ``interval`` keyword in the ``legend_kwds`` group of the ``plot()`` method
to control the appearance of the legend labels when using a classification
scheme (1605).
- The spatial index of a GeoSeries (accessed with the ``sindex`` attribute) is
now stored on the underlying array. This ensures that the spatial index is
preserved in more operations where possible, and that multiple geometry
columns of a GeoDataFrame can each have a spatial index (1444).
- Addition of a ``has_sindex`` attribute on the GeoSeries/GeoDataFrame to check
if a spatial index has already been initialized (1627).
- The ``geopandas.testing.assert_geoseries_equal()`` and ``assert_geodataframe_equal()``
testing utilities now have a ``normalize`` keyword (False by default) to
normalize geometries before comparing for equality (1826). Those functions
now also give a more informative error message when failing (1808).

Deprecations and compatibility notes:

- The ``is_ring`` attribute currently returns True for Polygons. In the future,
this will be False (1631). In addition, start to check it for LineStrings
and LinearRings (instead of always returning False).
- The deprecated ``objects`` keyword in the ``intersection()`` method of the
``GeoDataFrame/GeoSeries.sindex`` spatial index object has been removed
(1444).

Bug fixes:

- Fix regression in the ``plot()`` method raising an error with empty
geometries (1702, 1828).
- Fix ``geopandas.overlay()`` to preserve geometries of the correct type which
are nested within a GeometryCollection as a result of the overlay
operation (1582). In addition, a warning will now be raised if geometries
of different type are dropped from the result (1554).
- Fix the repr of an empty GeoSeries to not show spurious warnings (1673).
- Fix the ``.crs`` for empty GeoDataFrames (1560).
- Fix ``geopandas.clip`` to preserve the correct geometry column name (1566).
- Fix bug in ``plot()`` method when using ``legend_kwds`` with multiple subplots
(1583)
- Fix spurious warning with ``missing_kwds`` keyword of the ``plot()`` method
when there are no areas with missing data (1600).
- Fix the ``plot()`` method to correctly align values passed to the ``column``
keyword as a pandas Series (1670).
- Fix bug in plotting MultiPoints when passing values to determine the color
(1694)
- The ``rename_geometry()`` method now raises a more informative error message
when a duplicate column name is used (1602).
- Fix ``explode()`` method to preserve the CRS (1655)
- Fix the ``GeoSeries.apply()`` method to again accept the ``convert_dtype``
keyword to be consistent with pandas (1636).
- Fix ``GeoDataFrame.apply()`` to preserve the CRS when possible (1848).
- Fix bug in containment test as ``geom in geoseries`` (1753).
- The ``shift()`` method of a GeoSeries/GeoDataFrame now preserves the CRS
(1744).
- The PostGIS IO functionality now quotes table names to ensure it works with
case-sensitive names (1825).
- Fix the ``GeoSeries`` constructor without passing data but only an index (1798).

Notes on (optional) dependencies:

- GeoPandas 0.9.0 dropped support for Python 3.5. Further, the minimum
required versions are pandas 0.24, numpy 1.15 and shapely 1.6 and fiona 1.8.
- The ``descartes`` package is no longer required for plotting polygons. This
functionality is now included by default in GeoPandas itself, when
matplotlib is available (1677).
- Fiona is now only imported when used in ``read_file``/``to_file``. This means
you can now force geopandas to install without fiona installed (although it
is still a default requirement) (1775).
- Compatibility with the upcoming Shapely 1.8 (1659, 1662, 1819).