diff --git a/doc/source/_static/overlay_operations.png b/doc/source/_static/overlay_operations.png new file mode 100644 index 0000000..38beb8f Binary files /dev/null and b/doc/source/_static/overlay_operations.png differ diff --git a/doc/source/data_structures.rst b/doc/source/data_structures.rst index 96fb953..0f72ba1 100644 --- a/doc/source/data_structures.rst +++ b/doc/source/data_structures.rst @@ -70,7 +70,7 @@ Basic Methods Relationship Tests ^^^^^^^^^^^^^^^^^^^ -* ``almost_equals(other)``: is shape almost the same as ``other`` (good when floating point precision issues make shapes slightly different) +* ``geom_almost_equals(other)``: is shape almost the same as ``other`` (good when floating point precision issues make shapes slightly different) * ``contains(other)``: is shape contained within ``other`` * ``intersects(other)``: does shape intersect ``other`` diff --git a/doc/source/geometric_manipulations.rst b/doc/source/geometric_manipulations.rst index 2996ee2..29f6613 100644 --- a/doc/source/geometric_manipulations.rst +++ b/doc/source/geometric_manipulations.rst @@ -1,92 +1,74 @@ Geometric Manipulations ======================== +*geopandas* makes available all the tools for geometric manipulations in the `*shapely* library `_. - - -Set-theoretic Methods -~~~~~~~~~~~~~~~~~~~~~ - -.. attribute:: GeoSeries.boundary - - Returns a ``GeoSeries`` of lower dimensional objects representing - each geometries's set-theoretic `boundary`. - -.. method:: GeoSeries.difference(other) - - Returns a ``GeoSeries`` of the points in each geometry that - are not in the *other* object. - -.. method:: GeoSeries.intersection(other) - - Returns a ``GeoSeries`` of the intersection of each object with the `other` - geometric object. - -.. method:: GeoSeries.symmetric_difference(other) - - Returns a ``GeoSeries`` of the points in each object not in the `other` - geometric object, and the points in the `other` not in this object. - -.. method:: GeoSeries.union(other) - - Returns a ``GeoSeries`` of the union of points from each object and the - `other` geometric object. - - -.. attribute:: GeoSeries.unary_union - - Return a geometry containing the union of all geometries in the ``GeoSeries``. - +Note that documentation for all set-theoretic tools for creating new shapes using the relationship between two different spatial datasets -- like creating intersections, or differences -- can be found on the :doc:`set operations ` page. Constructive Methods -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~ -.. method:: GeoSeries.buffer(distance, resolution=16) +.. method:: GeoSeries.buffer(distance, resolution=16) Returns a ``GeoSeries`` of geometries representing all points within a given `distance` of each geometric object. -.. attribute:: GeoSeries.convex_hull +.. attribute:: GeoSeries.boundary + + Returns a ``GeoSeries`` of lower dimensional objects representing + each geometries's set-theoretic `boundary`. + +.. attribute:: GeoSeries.centroid + + Returns a ``GeoSeries`` of points for each geometric centroid. + +.. attribute:: GeoSeries.convex_hull Returns a ``GeoSeries`` of geometries representing the smallest convex `Polygon` containing all the points in each object unless the number of points in the object is less than three. For two points, the convex hull collapses to a `LineString`; for 1, a `Point`. -.. attribute:: GeoSeries.envelope +.. attribute:: GeoSeries.envelope Returns a ``GeoSeries`` of geometries representing the point or smallest rectangular polygon (with sides parallel to the coordinate axes) that contains each object. -.. method:: GeoSeries.simplify(tolerance, preserve_topology=True) +.. method:: GeoSeries.simplify(tolerance, preserve_topology=True) Returns a ``GeoSeries`` containing a simplified representation of each object. Affine transformations -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~ -.. method:: GeoSeries.rotate(self, angle, origin='center', use_radians=False) +.. method:: GeoSeries.rotate(self, angle, origin='center', use_radians=False) Rotate the coordinates of the GeoSeries. -.. method:: GeoSeries.scale(self, xfact=1.0, yfact=1.0, zfact=1.0, origin='center') +.. method:: GeoSeries.scale(self, xfact=1.0, yfact=1.0, zfact=1.0, origin='center') Scale the geometries of the GeoSeries along each (x, y, z) dimensio. -.. method:: GeoSeries.skew(self, angle, origin='center', use_radians=False) +.. method:: GeoSeries.skew(self, angle, origin='center', use_radians=False) Shear/Skew the geometries of the GeoSeries by angles along x and y dimensions. -.. method:: GeoSeries.translate(self, angle, origin='center', use_radians=False) +.. method:: GeoSeries.translate(self, angle, origin='center', use_radians=False) Shift the coordinates of the GeoSeries. -`Aggregating methods` +Aggregation Methods +~~~~~~~~~~~~~~~~~~~~ +.. attribute:: GeoSeries.unary_union + + Return a geometry containing the union of all geometries in the ``GeoSeries``. +Examples of Geometric Manipulations +------------------------------------ .. sourcecode:: python diff --git a/doc/source/index.rst b/doc/source/index.rst index 17d8c81..b380c35 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -32,6 +32,7 @@ such as PostGIS. Making Maps Managing Projections Geometric Manipulations + Set Operations with overlay Merging Data Geocoding Reference to All Attributes and Methods diff --git a/doc/source/reference.rst b/doc/source/reference.rst index a05e840..2b95ab7 100644 --- a/doc/source/reference.rst +++ b/doc/source/reference.rst @@ -124,15 +124,6 @@ The following Shapely methods and attributes are available on `Set-theoretic Methods` -.. attribute:: GeoSeries.boundary - - Returns a ``GeoSeries`` of lower dimensional objects representing - each geometries's set-theoretic `boundary`. - -.. attribute:: GeoSeries.centroid - - Returns a ``GeoSeries`` of points for each geometric centroid. - .. method:: GeoSeries.difference(other) Returns a ``GeoSeries`` of the points in each geometry that @@ -160,6 +151,15 @@ The following Shapely methods and attributes are available on Returns a ``GeoSeries`` of geometries representing all points within a given `distance` of each geometric object. +.. attribute:: GeoSeries.boundary + + Returns a ``GeoSeries`` of lower dimensional objects representing + each geometries's set-theoretic `boundary`. + +.. attribute:: GeoSeries.centroid + + Returns a ``GeoSeries`` of points for each geometric centroid. + .. attribute:: GeoSeries.convex_hull Returns a ``GeoSeries`` of geometries representing the smallest diff --git a/doc/source/set_operations.rst b/doc/source/set_operations.rst new file mode 100644 index 0000000..bd964ba --- /dev/null +++ b/doc/source/set_operations.rst @@ -0,0 +1,76 @@ +.. ipython:: python + :suppress: + + import geopandas as gpd + world = gpd.GeoDataFrame().from_file('_example_data/naturalearth_lowres.shp') + capitals = gpd.GeoDataFrame().from_file('_example_data/naturalearth_cities.shp') + + # For spatial join + countries = world[['geometry', 'name']] + + # Project + countries = countries.to_crs('+init=epsg:3395')[countries.name!="Antarctica"] + capitals = capitals.to_crs('+init=epsg:3395') + + +Set-Operations with Overlay +============================ + +When working with multiple spatial datasets -- especially multiple *polygon* or *line* datasets -- users often wish to create new shapes based on places where 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 ``overlay`` function. + +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 GeoDataFrame, this operation is executed against every other shape in the other GeoDataFrame: + +.. image:: _static/overlay_operations.png + +**Source: QGIS Documentation** + +(Note to users familiar with the *shapely* library: ``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 ``GeoSeries`` methods.) + + +Overlay Example +----------------- + +To illustrate the ``overlay`` function, 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. + +.. ipython:: python + + # Look at countries: + @savefig world_basic.png width=5in + countries.plot(); + + # Now buffer cities to find area within 500km. + # Check CRS -- World Mercator, units of meters. + capitals.crs + + # make 500km buffer + capitals['geometry']= capitals.buffer(500000) + @savefig capital_buffers.png width=5in + capitals.plot(); + + +To select only the portion of countries within 500km of a capital, we specify the ``how`` option to be "intersect", which creates a new set of polygons where these two layers overlap: + +.. ipython:: python + + from geopandas.tools import overlay + country_cores = overlay(countries, capitals, how='intersection') + @savefig country_cores.png width=5in + country_cores.plot(); + +Changing the "how" option allows for different types of overlay operations. For example, if we were interested in the portions of countries *far* from capitals (the peripheries), we would compute the difference of the two. + +.. ipython:: python + + country_peripheries = overlay(countries, capitals, how='difference') + @savefig country_peripheries.png width=5in + country_peripheries.plot(); + +More Examples +----------------- + +A larger set of examples of the use of ``overlay`` can be found `here `_ + + + +.. toctree:: + :maxdepth: 2