From dc4b5486960f9d080a85d8489e217eac4fadf43f Mon Sep 17 00:00:00 2001 From: Nick Eubank Date: Tue, 31 May 2016 07:56:17 -0700 Subject: [PATCH] final doc updates (#328) --- doc/source/aggregation_with_dissolve.rst | 51 ++++++++++++++++++++++++ doc/source/geometric_manipulations.rst | 25 +++++------- doc/source/index.rst | 1 + doc/source/mergingdata.rst | 4 +- doc/source/set_operations.rst | 5 +-- 5 files changed, 67 insertions(+), 19 deletions(-) create mode 100644 doc/source/aggregation_with_dissolve.rst diff --git a/doc/source/aggregation_with_dissolve.rst b/doc/source/aggregation_with_dissolve.rst new file mode 100644 index 0000000..a191fb5 --- /dev/null +++ b/doc/source/aggregation_with_dissolve.rst @@ -0,0 +1,51 @@ +.. ipython:: python + :suppress: + + import geopandas as gpd + + +Aggregation with dissolve +============================= + +It is often the case that we find ourselves working with spatial data that is more granular than we need. For example, we might have data on sub-national units, but we're actually interested in studying patterns at the level of countries. + +In a non-spatial setting, we aggregate our data using the ``groupby`` function. But when working with spatial data, we need a special tool that can also aggregate geometric features. In the *geopandas* library, that functionality is provided by the ``dissolve`` function. + +``dissolve`` can be thought of as doing three things: (a) it dissolves all the geometries within a given group together into a single geometric feature (using the ``unary_union`` method), and (b) it aggregates all the rows of data in a group using ``groupby.aggregate()``, and (c) it combines those two results. + +``dissolve`` Example +~~~~~~~~~~~~~~~~~~~~~ + +Suppose we are interested in studying continents, but we only have country-level data like the country dataset included in *geopandas*. We can easily convert this to a continent-level dataset. + + +First, let's look at the most simple case where we just want continent shapes and names. By default, ``dissolve`` will pass ``'first'`` to ``groupby.aggregate``. + +.. ipython:: python + + world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres')) + world = world[['continent', 'geometry']] + continents = world.dissolve(by='continent') + + @savefig continents.png width=5in + continents.plot(); + + continents.head() + +If we are interested in aggregate populations, however, we can pass different functions to the ``dissolve`` method to aggregate populations: + +.. ipython:: python + + world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres')) + world = world[['continent', 'geometry', 'pop_est']] + continents = world.dissolve(by='continent', aggfunc='sum') + + @savefig continents.png width=5in + continents.plot(column = 'pop_est', scheme='quantiles', cmap='YlOrRd'); + + continents.head() + + + +.. toctree:: + :maxdepth: 2 diff --git a/doc/source/geometric_manipulations.rst b/doc/source/geometric_manipulations.rst index 29f6613..b1b256c 100644 --- a/doc/source/geometric_manipulations.rst +++ b/doc/source/geometric_manipulations.rst @@ -1,7 +1,7 @@ Geometric Manipulations ======================== -*geopandas* makes available all the tools for geometric manipulations in the `*shapely* library `_. +*geopandas* makes available all the tools for geometric manipulations in the `*shapely* library `_. 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. @@ -40,6 +40,11 @@ Constructive Methods Returns a ``GeoSeries`` containing a simplified representation of each object. +.. attribute:: GeoSeries.unary_union + + Return a geometry containing the union of all geometries in the ``GeoSeries``. + + Affine transformations ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -59,16 +64,10 @@ Affine transformations Shift the coordinates of the GeoSeries. -Aggregation Methods -~~~~~~~~~~~~~~~~~~~~ - -.. attribute:: GeoSeries.unary_union - - Return a geometry containing the union of all geometries in the ``GeoSeries``. Examples of Geometric Manipulations ------------------------------------- +------------------------------------ .. sourcecode:: python @@ -128,7 +127,7 @@ GeoPandas also implements alternate constructors that can read any data format r 3 Brooklyn 1.959432e+09 726568.946340 4 Queens 3.049947e+09 861038.479299 5 Staten Island 1.623853e+09 330385.036974 - + geometry BoroCode 1 (POLYGON ((981219.0557861328125000 188655.3157... @@ -138,7 +137,7 @@ GeoPandas also implements alternate constructors that can read any data format r 5 (POLYGON ((970217.0223999023437500 145643.3322... .. image:: _static/nyc.png - + .. sourcecode:: python >>> boros['geometry'].convex_hull @@ -183,7 +182,7 @@ just use: >>> holes = boros['geometry'].intersection(mp) .. image:: _static/holes.png - + and to get the area outside of the holes: .. sourcecode:: python @@ -191,7 +190,7 @@ and to get the area outside of the holes: >>> boros_with_holes = boros['geometry'].difference(mp) .. image:: _static/boros_with_holes.png - + Note that this can be simplified a bit, since ``geometry`` is available as an attribute on a ``GeoDataFrame``, and the ``intersection`` and ``difference`` methods are implemented with the @@ -221,5 +220,3 @@ borough that are in the holes: .. toctree:: :maxdepth: 2 - - diff --git a/doc/source/index.rst b/doc/source/index.rst index b380c35..0395b88 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -33,6 +33,7 @@ such as PostGIS. Managing Projections Geometric Manipulations Set Operations with overlay + Aggregation with dissolve Merging Data Geocoding Reference to All Attributes and Methods diff --git a/doc/source/mergingdata.rst b/doc/source/mergingdata.rst index ce75ff2..3ebd69c 100644 --- a/doc/source/mergingdata.rst +++ b/doc/source/mergingdata.rst @@ -67,8 +67,8 @@ In a Spatial Join, two geometry objects are merged based on their spatial relati cities.head() # Execute spatial join - from geopandas.tools import sjoin - cities_with_country = sjoin(cities, countries, how="inner", op='intersects') + + cities_with_country = gpd.sjoin(cities, countries, how="inner", op='intersects') cities_with_country.head() diff --git a/doc/source/set_operations.rst b/doc/source/set_operations.rst index 2ffc57c..69d7f29 100644 --- a/doc/source/set_operations.rst +++ b/doc/source/set_operations.rst @@ -57,8 +57,7 @@ To select only the portion of countries within 500km of a capital, we specify th .. ipython:: python - from geopandas.tools import overlay - country_cores = overlay(countries, capitals, how='intersection') + country_cores = gpd.overlay(countries, capitals, how='intersection') @savefig country_cores.png width=5in country_cores.plot(); @@ -66,7 +65,7 @@ Changing the "how" option allows for different types of overlay operations. For .. ipython:: python - country_peripheries = overlay(countries, capitals, how='difference') + country_peripheries = gpd.overlay(countries, capitals, how='difference') @savefig country_peripheries.png width=5in country_peripheries.plot();