wassname/geopandas
1
0
Fork 0
mirror of https://github.com/wassname/geopandas.git synced 2026-09-21 13:00:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

API: expose sjoin_nearest, clip and overlay as methods (#2150)

Browse Source 
Co-authored-by: Brendan Ward <bcward@astutespruce.com>
Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>
This commit is contained in:
Martin Fleischmann
2021-10-03 19:45:07 +02:00
committed by GitHub
co-authored by Brendan Ward Joris Van den Bossche
parent 087858c12a
commit 0a7eebf6d1
14 changed files with 631 additions and 175 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/source/docs/user_guide/mergingdata.rst
+12 -8
View File
@@ -91,21 +91,25 @@ In a Spatial Join, two geometry objects are merged based on their spatial relati
# Execute spatial join
cities_with_country = geopandas.sjoin(cities, countries, how="inner", predicate='intersects')
cities_with_country = cities.sjoin(countries, how="inner", predicate='intersects')
cities_with_country.head()
GeoPandas provides two spatial-join functions:
- :func:`sjoin`: joins based on binary predicates (intersects, contains, etc.)
- :func:`sjoin_nearest`: joins based on proximity, with the ability to set a maximum search radius.
- :meth:`GeoDataFrame.sjoin`: joins based on binary predicates (intersects, contains, etc.)
- :meth:`GeoDataFrame.sjoin_nearest`: joins based on proximity, with the ability to set a maximum search radius.
.. note::
For historical reasons, both methods are also available as top-level functions :func:`sjoin` and :func:`sjoin_nearest`.
It is recommended to use methods as the functions may be deprecated in the future.
Binary Predicate Joins
~~~~~~~~~~~~~~~~~~~~~~
Binary predicate joins are available via :func:`sjoin`.
Binary predicate joins are available via :meth:`GeoDataFrame.sjoin`.
:func:`sjoin` has two core arguments: ``how`` and ``predicate``.
:meth:`GeoDataFrame.sjoin` has two core arguments: ``how`` and ``predicate``.
**predicate**
@@ -132,7 +136,7 @@ The `how` argument specifies the type of join that will occur and which geometry
:class:`GeoDataFrame`. It accepts the following options:
* ``left``: use the index from the first (or `left_df`) :class:`GeoDataFrame` that you provide
to :func:`sjoin`; retain only the `left_df` geometry column
to :meth:`GeoDataFrame.sjoin`; retain only the `left_df` geometry column
* ``right``: use index from second (or `right_df`); retain only the `right_df` geometry column
* ``inner``: use intersection of index values from both :class:`GeoDataFrame`; retain only the `left_df` geometry column
@@ -143,9 +147,9 @@ point into a circle of appropriate radius, then intersect those buffered circles
Nearest Joins
~~~~~~~~~~~~~
Proximity-based joins can be done via :func:`sjoin_nearest`.
Proximity-based joins can be done via :meth:`GeoDataFrame.sjoin_nearest`.
:func:`sjoin_nearest` shares the ``how`` argument with :func:`sjoin`, and
:meth:`GeoDataFrame.sjoin_nearest` shares the ``how`` argument with :meth:`GeoDataFrame.sjoin`, and
includes two additional arguments: ``max_distance`` and ``distance_col``.
**max_distance**
doc/source/docs/user_guide/set_operations.rst
+25 -18
View File
@@ -1,3 +1,5 @@
.. currentmodule:: geopandas
.. ipython:: python
:suppress:
@@ -14,22 +16,23 @@ When working with multiple spatial datasets -- especially multiple *polygon* or
those datasets overlap (or don't overlap). These manipulations are often
referred using the language of sets -- intersections, unions, and differences.
These types of operations are made available in the *geopandas* library through
the :func:`~geopandas.overlay` function.
the :meth:`~geopandas.GeoDataFrame.overlay` method.
The basic idea is demonstrated by the graphic below but keep in mind that
overlays operate at the DataFrame level, not on individual geometries, and the
properties from both are retained. In effect, for every shape in the first
:class:`~geopandas.GeoDataFrame`, this operation is executed against every other shape in the other
properties from both are retained. In effect, for every shape in the left
:class:`~geopandas.GeoDataFrame`, this operation is executed against every other shape in the right
:class:`~geopandas.GeoDataFrame`:
.. image:: ../../_static/overlay_operations.png
**Source: QGIS Documentation**
(Note to users familiar with the *shapely* library: :func:`~geopandas.overlay` can be thought
of as offering versions of the standard *shapely* set-operations that deal with
the complexities of applying set operations to two *GeoSeries*. The standard
*shapely* set-operations are also available as :class:`~geopandas.GeoSeries` methods.)
.. note::
Note to users familiar with the *shapely* library: :meth:`~geopandas.GeoDataFrame.overlay` can be thought
of as offering versions of the standard *shapely* set-operations that deal with
the complexities of applying set operations to two *GeoSeries*. The standard
*shapely* set-operations are also available as :class:`~geopandas.GeoSeries` methods.
The different Overlay operations
@@ -57,16 +60,20 @@ These two GeoDataFrames have some overlapping areas:
df2.plot(ax=ax, color='green', alpha=0.5);
We illustrate the different overlay modes with the above example.
The :func:`~geopandas.overlay` function will determine the set of all individual geometries
The :meth:`~geopandas.GeoDataFrame.overlay` method will determine the set of all individual geometries
from overlaying the two input GeoDataFrames. This result covers the area covered
by the two input GeoDataFrames, and also preserves all unique regions defined by
the combined boundaries of the two GeoDataFrames.
.. note::
For historical reasons, the overlay method is also available as a top-level function :func:`overlay`.
It is recommended to use the method as the function may be deprecated in the future.
When using ``how='union'``, all those possible geometries are returned:
.. ipython:: python
res_union = geopandas.overlay(df1, df2, how='union')
res_union = df1.overlay(df2, how='union')
res_union
ax = res_union.plot(alpha=0.5, cmap='tab10')
@@ -80,7 +87,7 @@ by both GeoDataFrames:
.. ipython:: python
res_intersection = geopandas.overlay(df1, df2, how='intersection')
res_intersection = df1.overlay(df2, how='intersection')
res_intersection
ax = res_intersection.plot(cmap='tab10')
@@ -93,7 +100,7 @@ the geometries that are only part of one of the GeoDataFrames but not of both:
.. ipython:: python
res_symdiff = geopandas.overlay(df1, df2, how='symmetric_difference')
res_symdiff = df1.overlay(df2, how='symmetric_difference')
res_symdiff
ax = res_symdiff.plot(cmap='tab10')
@@ -106,7 +113,7 @@ To obtain the geometries that are part of ``df1`` but are not contained in
.. ipython:: python
res_difference = geopandas.overlay(df1, df2, how='difference')
res_difference = df1.overlay(df2, how='difference')
res_difference
ax = res_difference.plot(cmap='tab10')
@@ -119,7 +126,7 @@ but with the geometries obtained from overlaying ``df1`` with ``df2``:
.. ipython:: python
res_identity = geopandas.overlay(df1, df2, how='identity')
res_identity = df1.overlay(df2, how='identity')
res_identity
ax = res_identity.plot(cmap='tab10')
@@ -146,7 +153,7 @@ First, we load the countries and cities example datasets and select :
countries = countries.to_crs('epsg:3395')
capitals = capitals.to_crs('epsg:3395')
To illustrate the :func:`~geopandas.overlay` function, consider the following case in which one
To illustrate the :meth:`~geopandas.GeoDataFrame.overlay` method, consider the following case in which one
wishes to identify the "core" portion of each country -- defined as areas within
500km of a capital -- using a ``GeoDataFrame`` of countries and a
``GeoDataFrame`` of capitals.
@@ -171,7 +178,7 @@ To select only the portion of countries within 500km of a capital, we specify th
.. ipython:: python
country_cores = geopandas.overlay(countries, capitals, how='intersection')
country_cores = countries.overlay(capitals, how='intersection')
@savefig country_cores.png width=5in
country_cores.plot(alpha=0.5, edgecolor='k', cmap='tab10');
@@ -179,7 +186,7 @@ Changing the "how" option allows for different types of overlay operations. For
.. ipython:: python
country_peripheries = geopandas.overlay(countries, capitals, how='difference')
country_peripheries = countries.overlay(capitals, how='difference')
@savefig country_peripheries.png width=5in
country_peripheries.plot(alpha=0.5, edgecolor='k', cmap='tab10');
@@ -194,7 +201,7 @@ Changing the "how" option allows for different types of overlay operations. For
keep_geom_type keyword
----------------------
In default settings, :func:`~geopandas.overlay` returns only geometries of the same geometry type as df1
In default settings, :meth:`~geopandas.GeoDataFrame.overlay` returns only geometries of the same geometry type as GeoDataFrame
(left one) has, where Polygon and MultiPolygon is considered as a same type (other types likewise).
You can control this behavior using ``keep_geom_type`` option, which is set to
True by default. Once set to False, ``overlay`` will return all geometry types resulting from
@@ -205,7 +212,7 @@ where two polygons intersects in a line or a point.
More Examples
-------------
A larger set of examples of the use of :func:`~geopandas.overlay` can be found `here <https://nbviewer.jupyter.org/github/geopandas/geopandas/blob/master/doc/source/gallery/overlays.ipynb>`_
A larger set of examples of the use of :meth:`~geopandas.GeoDataFrame.overlay` can be found `here <https://nbviewer.jupyter.org/github/geopandas/geopandas/blob/master/doc/source/gallery/overlays.ipynb>`_