mirror of
https://github.com/wassname/geopandas.git
synced 2026-09-26 13:50:17 +08:00
DOC: Relevant API links for intersphinx mapping (#1931)
* DOC: added API links to intersphinx mapping * DOC: updated mergingdata.rst links * DOC: updated aggregation_with_dissolve.rst links * DOC: updated data_structures.rst links * DOC: updated geocoding.rst links * DOC: updated geometric_manipulations.rst links * DOC: updated indexing.rst links * DOC: updated io.rst links * DOC: updated projections.rst links * DOC: updated set_operations.rst links * DOC: updated mapping.rst links * DOC: updated missing_empty.rst links * DOC: updated geoplot intersphinx links * DOC: make 'unary_union' attr instead of method Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: remove link to GeoDataFrame.geometry Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: convert pandas indexers to attrs instead of methods Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: convert indexer 'cx' to attr instead of method Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: refer GeoSeries.buffer instead of shapely buffer Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: make 'unary_union' attr instead of method on missing_empty.rst Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: refer to DataFrame.merge instead of pandas.merge Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net> * DOC: link pyproj.CRS * DOC: changed API links to 'stable' from 'latest' * DOC: fixed separator length * DOC: uppercase CRS in pyproj.crs Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net>
This commit is contained in:
Murat Can Üste
co-authored by
Martin Fleischmann
Martin Fleischmann
parent
dd2ed8efbf
commit
e2c5b0d978
+66
-3
@@ -66,8 +66,6 @@ autosummary_generate = True
|
||||
nbsphinx_execute = "always"
|
||||
nbsphinx_allow_errors = True
|
||||
|
||||
# connect docs in other projects
|
||||
intersphinx_mapping = {"pyproj": ("http://pyproj4.github.io/pyproj/stable/", None)}
|
||||
# suppress matplotlib warning in examples
|
||||
warnings.filterwarnings(
|
||||
"ignore",
|
||||
@@ -334,9 +332,74 @@ nbsphinx_prolog = r"""
|
||||
|
||||
# --Options for sphinx extensions -----------------------------------------------
|
||||
|
||||
# connect docs in other projects
|
||||
intersphinx_mapping = {
|
||||
"pyproj": (
|
||||
"https://pyproj4.github.io/pyproj/stable/",
|
||||
"https://pyproj4.github.io/pyproj/stable/objects.inv",
|
||||
),
|
||||
"pandas": (
|
||||
"https://pandas.pydata.org/pandas-docs/stable/",
|
||||
"https://pandas.pydata.org/pandas-docs/stable/objects.inv",
|
||||
),
|
||||
}
|
||||
"shapely": (
|
||||
"https://shapely.readthedocs.io/en/stable/",
|
||||
"https://shapely.readthedocs.io/en/stable/objects.inv",
|
||||
),
|
||||
"fiona": (
|
||||
"https://fiona.readthedocs.io/en/stable/",
|
||||
"https://fiona.readthedocs.io/en/stable/objects.inv",
|
||||
),
|
||||
"pygeos": (
|
||||
"https://pygeos.readthedocs.io/en/latest/",
|
||||
"https://pygeos.readthedocs.io/en/latest/objects.inv",
|
||||
),
|
||||
"rtree": (
|
||||
"https://rtree.readthedocs.io/en/stable/",
|
||||
"https://rtree.readthedocs.io/en/stable/objects.inv",
|
||||
),
|
||||
"mapclassify": (
|
||||
"https://pysal.org/mapclassify/",
|
||||
"https://pysal.org/mapclassify/objects.inv"
|
||||
),
|
||||
"libpysal": (
|
||||
"https://pysal.org/libpysal/",
|
||||
"https://pysal.org/libpysal/objects.inv"
|
||||
),
|
||||
"matplotlib": (
|
||||
"https://matplotlib.org/stable/",
|
||||
"https://matplotlib.org/stable/objects.inv",
|
||||
),
|
||||
"geopy": (
|
||||
"https://geopy.readthedocs.io/en/stable/",
|
||||
"https://geopy.readthedocs.io/en/stable/objects.inv",
|
||||
),
|
||||
"cartopy": (
|
||||
"https://scitools.org.uk/cartopy/docs/latest/",
|
||||
"https://scitools.org.uk/cartopy/docs/latest/objects.inv"
|
||||
),
|
||||
"pyepsg": (
|
||||
"https://pyepsg.readthedocs.io/en/stable/",
|
||||
"https://pyepsg.readthedocs.io/en/stable/objects.inv"
|
||||
),
|
||||
"contextily": (
|
||||
"https://contextily.readthedocs.io/en/stable/",
|
||||
"https://contextily.readthedocs.io/en/stable/objects.inv"
|
||||
),
|
||||
"rasterio": (
|
||||
"https://rasterio.readthedocs.io/en/stable/",
|
||||
"https://rasterio.readthedocs.io/en/stable/objects.inv"
|
||||
),
|
||||
"geoplot": (
|
||||
"https://residentmario.github.io/geoplot/index.html",
|
||||
"https://residentmario.github.io/geoplot/objects.inv"
|
||||
),
|
||||
"folium": (
|
||||
"https://python-visualization.github.io/folium/",
|
||||
"https://python-visualization.github.io/folium/objects.inv"
|
||||
),
|
||||
"python": (
|
||||
"https://docs.python.org/3",
|
||||
"https://docs.python.org/3/objects.inv"
|
||||
)
|
||||
}
|
||||
|
||||
@@ -12,17 +12,21 @@ Aggregation with dissolve
|
||||
|
||||
Spatial data are often 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, when all we need are summary statistics of the data, we aggregate our data using the ``groupby`` function. But for spatial data, we sometimes also need to aggregate geometric features. In the *geopandas* library, we can aggregate geometric features using the ``dissolve`` function.
|
||||
In a non-spatial setting, when all we need are summary statistics of the data, we aggregate our data using the :meth:`~pandas.DataFrame.groupby` function. But for spatial data, we sometimes also need to aggregate geometric features. In the *geopandas* library, we can aggregate geometric features using the :meth:`~geopandas.GeoDataFrame.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.
|
||||
:meth:`~geopandas.GeoDataFrame.dissolve` can be thought of as doing three things:
|
||||
|
||||
``dissolve`` Example
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
(a) it dissolves all the geometries within a given group together into a single geometric feature (using the :attr:`~geopandas.GeoSeries.unary_union` method), and
|
||||
(b) it aggregates all the rows of data in a group using :ref:`groupby.aggregate <groupby.aggregate>`, and
|
||||
(c) it combines those two results.
|
||||
|
||||
:meth:`~geopandas.GeoDataFrame.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``.
|
||||
First, let's look at the most simple case where we just want continent shapes and names. By default, :meth:`~geopandas.GeoDataFrame.dissolve` will pass ``'first'`` to :ref:`groupby.aggregate <groupby.aggregate>`.
|
||||
|
||||
.. ipython:: python
|
||||
|
||||
@@ -35,7 +39,7 @@ First, let's look at the most simple case where we just want continent shapes an
|
||||
|
||||
continents.head()
|
||||
|
||||
If we are interested in aggregate populations, however, we can pass different functions to the ``dissolve`` method to aggregate populations using the ``aggfunc =`` argument:
|
||||
If we are interested in aggregate populations, however, we can pass different functions to the :meth:`~geopandas.GeoDataFrame.dissolve` method to aggregate populations using the ``aggfunc =`` argument:
|
||||
|
||||
.. ipython:: python
|
||||
|
||||
@@ -62,7 +66,7 @@ Dissolve Arguments
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``aggfunc =`` argument defaults to 'first' which means that the first row of attributes values found in the dissolve routine will be assigned to the resultant dissolved geodataframe.
|
||||
However it also accepts other summary statistic options as allowed by ``pandas.groupby()`` including:
|
||||
However it also accepts other summary statistic options as allowed by :meth:`pandas.groupby <pandas.DataFrame.groupby>` including:
|
||||
|
||||
* 'first'
|
||||
* 'last'
|
||||
|
||||
@@ -14,8 +14,8 @@ Data Structures
|
||||
=========================================
|
||||
|
||||
GeoPandas implements two main data structures, a :class:`GeoSeries` and a
|
||||
:class:`GeoDataFrame`. These are subclasses of pandas ``Series`` and
|
||||
``DataFrame``, respectively.
|
||||
:class:`GeoDataFrame`. These are subclasses of :class:`pandas.Series` and
|
||||
:class:`pandas.DataFrame`, respectively.
|
||||
|
||||
GeoSeries
|
||||
---------
|
||||
@@ -45,7 +45,7 @@ operation is carried out elementwise. The two series will be aligned
|
||||
by matching indices. Binary operations can also be applied to a
|
||||
single geometry, in which case the operation is carried out for each
|
||||
element of the series with that geometry. In either case, a
|
||||
``Series`` or a :class:`GeoSeries` will be returned, as appropriate.
|
||||
:class:`~pandas.Series` or a :class:`GeoSeries` will be returned, as appropriate.
|
||||
|
||||
A short summary of a few attributes and methods for GeoSeries is
|
||||
presented here, and a full list can be found in the :doc:`all attributes and methods page <../reference/geoseries>`.
|
||||
@@ -64,7 +64,7 @@ Attributes
|
||||
Basic Methods
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
* :meth:`~GeoSeries.distance`: returns ``Series`` with minimum distance from each entry to ``other``
|
||||
* :meth:`~GeoSeries.distance`: returns :class:`~pandas.Series` with minimum distance from each entry to ``other``
|
||||
* :attr:`~GeoSeries.centroid`: returns :class:`GeoSeries` of centroids
|
||||
* :meth:`~GeoSeries.representative_point`: returns :class:`GeoSeries` of points that are guaranteed to be within each geometry. It does **NOT** return centroids.
|
||||
* :meth:`~GeoSeries.to_crs`: change coordinate reference system. See :doc:`projections <projections>`
|
||||
@@ -129,14 +129,14 @@ Now, we create centroids and make it the geometry:
|
||||
|
||||
gdf = gdf.rename(columns={'old_name': 'new_name'}).set_geometry('new_name')
|
||||
|
||||
**Note 2:** Somewhat confusingly, by default when you use the ``read_file`` command, the column containing spatial objects from the file is named "geometry" by default, and will be set as the active geometry column. However, despite using the same term for the name of the column and the name of the special attribute that keeps track of the active column, they are distinct. You can easily shift the active geometry column to a different :class:`GeoSeries` with the :meth:`~GeoDataFrame.set_geometry` command. Further, ``gdf.geometry`` will always return the active geometry column, *not* the column named ``geometry``. If you wish to call a column named "geometry", and a different column is the active geometry column, use ``gdf['geometry']``, not ``gdf.geometry``.
|
||||
**Note 2:** Somewhat confusingly, by default when you use the :func:`~geopandas.read_file` command, the column containing spatial objects from the file is named "geometry" by default, and will be set as the active geometry column. However, despite using the same term for the name of the column and the name of the special attribute that keeps track of the active column, they are distinct. You can easily shift the active geometry column to a different :class:`GeoSeries` with the :meth:`~GeoDataFrame.set_geometry` command. Further, ``gdf.geometry`` will always return the active geometry column, *not* the column named ``geometry``. If you wish to call a column named "geometry", and a different column is the active geometry column, use ``gdf['geometry']``, not ``gdf.geometry``.
|
||||
|
||||
Attributes and Methods
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Any of the attributes calls or methods described for a :class:`GeoSeries` will work on a :class:`GeoDataFrame` -- effectively, they are just applied to the "geometry" :class:`GeoSeries`.
|
||||
|
||||
However, ``GeoDataFrames`` also have a few extra methods for input and output which are described on the :doc:`Input and Output <io>` page and for geocoding with are described in :doc:`Geocoding <geocoding>`.
|
||||
However, :class:`GeoDataFrames <GeoDataFrame>` also have a few extra methods for input and output which are described on the :doc:`Input and Output <io>` page and for geocoding with are described in :doc:`Geocoding <geocoding>`.
|
||||
|
||||
|
||||
.. ipython:: python
|
||||
|
||||
@@ -32,17 +32,17 @@ with the detailed borough boundary file included within ``geopandas``.
|
||||
boro_locations.plot(ax=ax, color="red");
|
||||
|
||||
|
||||
By default, the ``geocode`` function uses the
|
||||
By default, the :func:`~geopandas.tools.geocode` function uses the
|
||||
`GeoCode.Farm geocoding API <https://geocode.farm/>`__ with a rate limitation
|
||||
applied. But a different geocoding service can be specified with the
|
||||
``provider`` keyword.
|
||||
|
||||
The argument to ``provider`` can either be a string referencing geocoding
|
||||
services, such as ``'google'``, ``'bing'``, ``'yahoo'``, and
|
||||
``'openmapquest'``, or an instance of a ``Geocoder`` from ``geopy``. See
|
||||
``'openmapquest'``, or an instance of a :mod:`Geocoder <geopy.geocoders>` from :mod:`geopy`. See
|
||||
``geopy.geocoders.SERVICE_TO_GEOCODER`` for the full list.
|
||||
For many providers, parameters such as API keys need to be passed as
|
||||
``**kwargs`` in the ``geocode`` call.
|
||||
``**kwargs`` in the :func:`~geopandas.tools.geocode` call.
|
||||
|
||||
For example, to use the OpenStreetMap Nominatim geocoder, you need to specify
|
||||
a user agent:
|
||||
|
||||
@@ -12,39 +12,39 @@ Constructive Methods
|
||||
|
||||
.. method:: GeoSeries.buffer(distance, resolution=16)
|
||||
|
||||
Returns a ``GeoSeries`` of geometries representing all points within a given `distance`
|
||||
Returns a :class:`~geopandas.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
|
||||
Returns a :class:`~geopandas.GeoSeries` of lower dimensional objects representing
|
||||
each geometries's set-theoretic `boundary`.
|
||||
|
||||
.. attribute:: GeoSeries.centroid
|
||||
|
||||
Returns a ``GeoSeries`` of points for each geometric centroid.
|
||||
Returns a :class:`~geopandas.GeoSeries` of points for each geometric centroid.
|
||||
|
||||
.. attribute:: GeoSeries.convex_hull
|
||||
|
||||
Returns a ``GeoSeries`` of geometries representing the smallest
|
||||
Returns a :class:`~geopandas.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
|
||||
|
||||
Returns a ``GeoSeries`` of geometries representing the point or
|
||||
Returns a :class:`~geopandas.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)
|
||||
|
||||
Returns a ``GeoSeries`` containing a simplified representation of
|
||||
Returns a :class:`~geopandas.GeoSeries` containing a simplified representation of
|
||||
each object.
|
||||
|
||||
.. attribute:: GeoSeries.unary_union
|
||||
|
||||
Return a geometry containing the union of all geometries in the ``GeoSeries``.
|
||||
Return a geometry containing the union of all geometries in the :class:`~geopandas.GeoSeries`.
|
||||
|
||||
|
||||
Affine transformations
|
||||
@@ -52,23 +52,23 @@ Affine transformations
|
||||
|
||||
.. method:: GeoSeries.affine_transform(self, matrix)
|
||||
|
||||
Transform the geometries of the GeoSeries using an affine transformation matrix
|
||||
Transform the geometries of the :class:`~geopandas.GeoSeries` using an affine transformation matrix
|
||||
|
||||
.. method:: GeoSeries.rotate(self, angle, origin='center', use_radians=False)
|
||||
|
||||
Rotate the coordinates of the GeoSeries.
|
||||
Rotate the coordinates of the :class:`~geopandas.GeoSeries`.
|
||||
|
||||
.. 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.
|
||||
Scale the geometries of the :class:`~geopandas.GeoSeries` along each (x, y, z) dimensio.
|
||||
|
||||
.. method:: GeoSeries.skew(self, angle, origin='center', use_radians=False)
|
||||
|
||||
Shear/Skew the geometries of the GeoSeries by angles along x and y dimensions.
|
||||
Shear/Skew the geometries of the :class:`~geopandas.GeoSeries` by angles along x and y dimensions.
|
||||
|
||||
.. method:: GeoSeries.translate(self, xoff=0.0, yoff=0.0, zoff=0.0)
|
||||
|
||||
Shift the coordinates of the GeoSeries.
|
||||
Shift the coordinates of the :class:`~geopandas.GeoSeries`.
|
||||
|
||||
|
||||
|
||||
@@ -92,7 +92,7 @@ Examples of Geometric Manipulations
|
||||
|
||||
.. image:: ../../_static/test.png
|
||||
|
||||
Some geographic operations return normal pandas object. The ``area`` property of a ``GeoSeries`` will return a ``pandas.Series`` containing the area of each item in the ``GeoSeries``:
|
||||
Some geographic operations return normal pandas object. The :attr:`~geopandas.GeoSeries.area` property of a :class:`~geopandas.GeoSeries` will return a :class:`pandas.Series` containing the area of each item in the :class:`~geopandas.GeoSeries`:
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
@@ -161,7 +161,7 @@ GeoPandas also implements alternate constructors that can read any data format r
|
||||
.. image:: ../../_static/nyc_hull.png
|
||||
|
||||
To demonstrate a more complex operation, we'll generate a
|
||||
``GeoSeries`` containing 2000 random points:
|
||||
:class:`~geopandas.GeoSeries` containing 2000 random points:
|
||||
|
||||
.. sourcecode:: python
|
||||
|
||||
@@ -178,7 +178,7 @@ Now draw a circle with fixed radius around each point:
|
||||
|
||||
>>> circles = pts.buffer(2000)
|
||||
|
||||
We can collapse these circles into a single shapely MultiPolygon
|
||||
We can collapse these circles into a single :class:`MultiPolygon`
|
||||
geometry with
|
||||
|
||||
.. sourcecode:: python
|
||||
@@ -203,8 +203,8 @@ and to get the area outside of the holes:
|
||||
.. 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
|
||||
available as an attribute on a :class:`~geopandas.GeoDataFrame`, and the
|
||||
:meth:`~geopandas.GeoSeries.intersection` and :meth:`~geopandas.GeoSeries.difference` methods are implemented with the
|
||||
"&" and "-" operators, respectively. For example, the latter could
|
||||
have been expressed simply as ``boros.geometry - mp``.
|
||||
|
||||
|
||||
@@ -9,13 +9,13 @@
|
||||
Indexing and Selecting Data
|
||||
===========================
|
||||
|
||||
GeoPandas inherits the standard ``pandas`` methods for indexing/selecting data. This includes label based indexing with ``.loc`` and integer position based indexing with ``.iloc``, which apply to both ``GeoSeries`` and ``GeoDataFrame`` objects. For more information on indexing/selecting, see the pandas_ documentation.
|
||||
GeoPandas inherits the standard pandas_ methods for indexing/selecting data. This includes label based indexing with :attr:`~pandas.DataFrame.loc` and integer position based indexing with :attr:`~pandas.DataFrame.iloc`, which apply to both :class:`GeoSeries` and :class:`GeoDataFrame` objects. For more information on indexing/selecting, see the pandas_ documentation.
|
||||
|
||||
.. _pandas: http://pandas.pydata.org/pandas-docs/stable/indexing.html
|
||||
|
||||
In addition to the standard ``pandas`` methods, GeoPandas also provides
|
||||
coordinate based indexing with the ``cx`` indexer, which slices using a bounding
|
||||
box. Geometries in the ``GeoSeries`` or ``GeoDataFrame`` that intersect the
|
||||
In addition to the standard pandas_ methods, GeoPandas also provides
|
||||
coordinate based indexing with the :attr:`~GeoDataFrame.cx` indexer, which slices using a bounding
|
||||
box. Geometries in the :class:`GeoSeries` or :class:`GeoDataFrame` that intersect the
|
||||
bounding box will be returned.
|
||||
|
||||
Using the ``world`` dataset, we can use this functionality to quickly select all
|
||||
@@ -27,4 +27,3 @@ countries whose boundaries extend into the southern hemisphere.
|
||||
southern_world = world.cx[:, :0]
|
||||
@savefig world_southern.png
|
||||
southern_world.plot(figsize=(10, 3));
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ library, which in turn makes use of a massive open-source program called
|
||||
transformations.
|
||||
|
||||
Any arguments passed to :func:`geopandas.read_file` after the file name will be
|
||||
passed directly to ``fiona.open``, which does the actual data importation. In
|
||||
passed directly to :func:`fiona.open`, which does the actual data importation. In
|
||||
general, :func:`geopandas.read_file` is pretty smart and should do what you want
|
||||
without extra arguments, but for more help, type::
|
||||
|
||||
@@ -30,7 +30,7 @@ the ``layer`` keyword::
|
||||
|
||||
countries_gdf = geopandas.read_file("package.gpkg", layer='countries')
|
||||
|
||||
Where supported in ``fiona``, *geopandas* can also load resources directly from
|
||||
Where supported in :mod:`fiona`, *geopandas* can also load resources directly from
|
||||
a web URL, for example for GeoJSON files from `geojson.xyz <http://geojson.xyz/>`_::
|
||||
|
||||
url = "http://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_110m_land.geojson"
|
||||
@@ -50,8 +50,8 @@ specify the filename::
|
||||
|
||||
zipfile = "zip:///Users/name/Downloads/gadm36_AFG_shp.zip!data/gadm36_AFG_1.shp"
|
||||
|
||||
It is also possible to read any file-like objects with a ``read()`` method, such
|
||||
as a file handler (e.g. via built-in ``open`` function) or ``StringIO``::
|
||||
It is also possible to read any file-like objects with a :func:`os.read` method, such
|
||||
as a file handler (e.g. via built-in :func:`open` function) or :class:`~io.StringIO`::
|
||||
|
||||
filename = "test.geojson"
|
||||
file = open(filename)
|
||||
|
||||
@@ -15,7 +15,9 @@ Mapping and Plotting Tools
|
||||
=========================================
|
||||
|
||||
|
||||
*geopandas* provides a high-level interface to the ``matplotlib`` library for making maps. Mapping shapes is as easy as using the ``plot()`` method on a ``GeoSeries`` or ``GeoDataFrame``.
|
||||
*geopandas* provides a high-level interface to the matplotlib_ library for making maps. Mapping shapes is as easy as using the :meth:`~GeoDataFrame.plot()` method on a :class:`GeoSeries` or :class:`GeoDataFrame`.
|
||||
|
||||
.. _matplotlib: https://matplotlib.org/stable/
|
||||
|
||||
Loading some example data:
|
||||
|
||||
@@ -35,7 +37,7 @@ We can now plot those GeoDataFrames:
|
||||
@savefig world_randomcolors.png
|
||||
world.plot();
|
||||
|
||||
Note that in general, any options one can pass to `pyplot <http://matplotlib.org/api/pyplot_api.html>`_ in ``matplotlib`` (or `style options that work for lines <http://matplotlib.org/api/lines_api.html>`_) can be passed to the ``plot()`` method.
|
||||
Note that in general, any options one can pass to `pyplot <http://matplotlib.org/api/pyplot_api.html>`_ in matplotlib_ (or `style options that work for lines <http://matplotlib.org/api/lines_api.html>`_) can be passed to the :meth:`~GeoDataFrame.plot` method.
|
||||
|
||||
|
||||
Choropleth Maps
|
||||
@@ -65,7 +67,7 @@ When plotting a map, one can enable a legend using the ``legend`` argument:
|
||||
@savefig world_pop_est.png
|
||||
world.plot(column='pop_est', ax=ax, legend=True)
|
||||
|
||||
However, the default appearance of the legend and plot axes may not be desirable. One can define the plot axes (with ``ax``) and the legend axes (with ``cax``) and then pass those in to the ``plot`` call. The following example uses ``mpl_toolkits`` to vertically align the plot axes and the legend axes:
|
||||
However, the default appearance of the legend and plot axes may not be desirable. One can define the plot axes (with ``ax``) and the legend axes (with ``cax``) and then pass those in to the :meth:`~GeoDataFrame.plot` call. The following example uses ``mpl_toolkits`` to vertically align the plot axes and the legend axes:
|
||||
|
||||
.. ipython:: python
|
||||
|
||||
@@ -96,7 +98,7 @@ And the following example plots the color bar below the map and adds its label u
|
||||
Choosing colors
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
One can also modify the colors used by ``plot`` with the ``cmap`` option (for a full list of colormaps, see the `matplotlib website <http://matplotlib.org/users/colormaps.html>`_):
|
||||
One can also modify the colors used by :meth:`~GeoDataFrame.plot` with the ``cmap`` option (for a full list of colormaps, see the `matplotlib website <http://matplotlib.org/users/colormaps.html>`_):
|
||||
|
||||
.. ipython:: python
|
||||
|
||||
|
||||
@@ -11,11 +11,11 @@ Merging Data
|
||||
|
||||
There are two ways to combine datasets in *geopandas* -- attribute joins and spatial joins.
|
||||
|
||||
In an attribute join, a :py:class:`GeoSeries` or :py:class:`GeoDataFrame` is
|
||||
combined with a regular :py:class:`pandas.Series` or :py:class:`pandas.DataFrame` based on a
|
||||
In an attribute join, a :class:`GeoSeries` or :class:`GeoDataFrame` is
|
||||
combined with a regular :class:`pandas.Series` or :class:`pandas.DataFrame` based on a
|
||||
common variable. This is analogous to normal merging or joining in *pandas*.
|
||||
|
||||
In a Spatial Join, observations from two :py:class:`GeoSeries` or :py:class:`GeoDataFrame`
|
||||
In a Spatial Join, observations from two :class:`GeoSeries` or :class:`GeoDataFrame`
|
||||
are combined based on their spatial relationship to one another.
|
||||
|
||||
In the following examples, we use these datasets:
|
||||
@@ -37,7 +37,7 @@ In the following examples, we use these datasets:
|
||||
Appending
|
||||
---------
|
||||
|
||||
Appending :py:class:`GeoDataFrame` and :py:class:`GeoSeries` uses pandas ``append`` methods.
|
||||
Appending :class:`GeoDataFrame` and :class:`GeoSeries` uses pandas :meth:`~pandas.DataFrame.append` methods.
|
||||
Keep in mind, that appended geometry columns needs to have the same CRS.
|
||||
|
||||
.. ipython:: python
|
||||
@@ -54,14 +54,14 @@ Keep in mind, that appended geometry columns needs to have the same CRS.
|
||||
Attribute Joins
|
||||
----------------
|
||||
|
||||
Attribute joins are accomplished using the ``merge`` method. In general, it is recommended
|
||||
to use the ``merge`` method called from the spatial dataset. With that said, the stand-alone
|
||||
``merge`` function will work if the :py:class:`GeoDataFrame` is in the ``left`` argument;
|
||||
if a :py:class:`pandas.DataFrame` is in the ``left`` argument and a :py:class:`GeoDataFrame`
|
||||
is in the ``right`` position, the result will no longer be a :py:class:`GeoDataFrame`.
|
||||
Attribute joins are accomplished using the :meth:`~pandas.DataFrame.merge` method. In general, it is recommended
|
||||
to use the ``merge()`` method called from the spatial dataset. With that said, the stand-alone
|
||||
:func:`pandas.merge` function will work if the :class:`GeoDataFrame` is in the ``left`` argument;
|
||||
if a :class:`~pandas.DataFrame` is in the ``left`` argument and a :class:`GeoDataFrame`
|
||||
is in the ``right`` position, the result will no longer be a :class:`GeoDataFrame`.
|
||||
|
||||
For example, consider the following merge that adds full names to a :py:class:`GeoDataFrame`
|
||||
that initially has only ISO codes for each country by merging it with a :py:class:`pandas.DataFrame`.
|
||||
For example, consider the following merge that adds full names to a :class:`GeoDataFrame`
|
||||
that initially has only ISO codes for each country by merging it with a :class:`~pandas.DataFrame`.
|
||||
|
||||
.. ipython:: python
|
||||
|
||||
@@ -98,7 +98,7 @@ In a Spatial Join, two geometry objects are merged based on their spatial relati
|
||||
Sjoin Arguments
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
:py:class:`sjoin` has two core arguments: ``how`` and ``op``.
|
||||
:func:`sjoin` has two core arguments: ``how`` and ``op``.
|
||||
|
||||
**op**
|
||||
|
||||
@@ -122,13 +122,13 @@ defined in the
|
||||
**how**
|
||||
|
||||
The `how` argument specifies the type of join that will occur and which geometry is retained in the resultant
|
||||
:py:class:`GeoDataFrame`. It accepts the following options:
|
||||
:class:`GeoDataFrame`. It accepts the following options:
|
||||
|
||||
* ``left``: use the index from the first (or `left_df`) :py:class:`GeoDataFrame` that you provide
|
||||
to ``sjoin``; retain only the `left_df` geometry column
|
||||
* ``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
|
||||
* ``right``: use index from second (or `right_df`); retain only the `right_df` geometry column
|
||||
* ``inner``: use intersection of index values from both :py:class:`GeoDataFrame`; retain only the `left_df` geometry column
|
||||
* ``inner``: use intersection of index values from both :class:`GeoDataFrame`; retain only the `left_df` geometry column
|
||||
|
||||
Note more complicated spatial relationships can be studied by combining geometric operations with spatial join.
|
||||
To find all polygons within a given distance of a point, for example, one can first use the ``buffer`` method to expand each
|
||||
To find all polygons within a given distance of a point, for example, one can first use the :meth:`~geopandas.GeoSeries.buffer` method to expand each
|
||||
point into a circle of appropriate radius, then intersect those buffered circles with the polygons in question.
|
||||
|
||||
@@ -22,7 +22,7 @@ empty geometries:
|
||||
a Shapely geometry object.
|
||||
- **Missing geometries** are unknown values in a GeoSeries. They will typically
|
||||
be propagated in operations (for example in calculations of the area or of
|
||||
the intersection), or ignored in reductions such as ``unary_union``.
|
||||
the intersection), or ignored in reductions such as :attr:`~GeoSeries.unary_union`.
|
||||
The scalar object (when accessing a single element of a GeoSeries) is the
|
||||
Python ``None`` object.
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ referred to using the authority code ``"EPSG:4326"``.
|
||||
- CRS WKT string
|
||||
- An authority string (i.e. "epsg:4326")
|
||||
- An EPSG integer code (i.e. 4326)
|
||||
- A ``pyproj.CRS``
|
||||
- A :class:`pyproj.CRS <pyproj.crs.CRS>`
|
||||
- An object with a to_wkt method.
|
||||
- PROJ string
|
||||
- Dictionary of PROJ parameters
|
||||
@@ -145,7 +145,7 @@ Upgrading to GeoPandas 0.7 with pyproj > 2.2 and PROJ > 6
|
||||
---------------------------------------------------------
|
||||
|
||||
Starting with GeoPandas 0.7, the `.crs` attribute of a GeoSeries or GeoDataFrame
|
||||
stores the CRS information as a ``pyproj.CRS``, and no longer as a proj4 string
|
||||
stores the CRS information as a :class:`pyproj.CRS <pyproj.crs.CRS>`, and no longer as a proj4 string
|
||||
or dict.
|
||||
|
||||
Before, you might have seen this:
|
||||
@@ -176,7 +176,7 @@ for some more background, and the subsections below cover different possible
|
||||
migration issues.
|
||||
|
||||
See the `pyproj docs <https://pyproj4.github.io/pyproj/stable/>`__ for more on
|
||||
the ``pyproj.CRS`` object.
|
||||
the :class:`pyproj.CRS <pyproj.crs.CRS>` object.
|
||||
|
||||
Importing data from files
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -267,11 +267,11 @@ including their EPSG codes and proj4 string definitions.
|
||||
**Other formats**
|
||||
|
||||
Next to the EPSG code mentioned above, there are also other ways to specify the
|
||||
CRS: an actual ``pyproj.CRS`` object, a WKT string, a PROJ JSON string, etc.
|
||||
Anything that is accepted by ``pyproj.CRS.from_user_input`` can by specified
|
||||
CRS: an actual :class:`pyproj.CRS <pyproj.crs.CRS>` object, a WKT string, a PROJ JSON string, etc.
|
||||
Anything that is accepted by :meth:`pyproj.CRS.from_user_input() <pyproj.crs.CRS.from_user_input>` can by specified
|
||||
to the ``crs`` keyword/attribute in GeoPandas.
|
||||
|
||||
Also compatible CRS objects, such as from the ``rasterio`` package, can be
|
||||
Also compatible CRS objects, such as from the :mod:`rasterio` package, can be
|
||||
passed directly to GeoPandas.
|
||||
|
||||
|
||||
@@ -306,7 +306,7 @@ Why is it not properly recognizing my CRS?
|
||||
There are many file sources and CRS definitions out there "in the wild" that
|
||||
might have a CRS description that does not fully conform to the new standards of
|
||||
PROJ > 6 (proj4 strings, older WKT formats, ...). In such cases, you will get a
|
||||
``pyproj.CRS`` object that might not be fully what you expected (e.g. not equal
|
||||
:class:`pyproj.CRS <pyproj.crs.CRS>` object that might not be fully what you expected (e.g. not equal
|
||||
to the expected EPSG code). Below we list a few possible cases.
|
||||
|
||||
I get a "Bound CRS"?
|
||||
@@ -447,7 +447,7 @@ The ``.crs`` attribute is no longer a dict or string
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you relied on the ``.crs`` object being a dict or a string, such code can
|
||||
be broken given it is now a ``pyproj.CRS`` object. But this object actually
|
||||
be broken given it is now a :class:`pyproj.CRS <pyproj.crs.CRS>` object. But this object actually
|
||||
provides a more robust interface to get information about the CRS.
|
||||
|
||||
For example, if you used the following code to get the EPSG code:
|
||||
@@ -457,7 +457,7 @@ For example, if you used the following code to get the EPSG code:
|
||||
gdf.crs['init']
|
||||
|
||||
This will no longer work. To get the EPSG code from a ``crs`` object, you can use
|
||||
the ``to_epsg()`` method.
|
||||
the :meth:`~pyproj.crs.CRS.to_epsg` method.
|
||||
|
||||
Or to check if a CRS was a certain UTM zone:
|
||||
|
||||
@@ -471,5 +471,5 @@ could be replaced with the more robust check (requires pyproj 2.6+):
|
||||
|
||||
gdf.crs.utm_zone is not None
|
||||
|
||||
And there are many other methods available on the ``pyproj.CRS`` class to get
|
||||
And there are many other methods available on the :class:`pyproj.CRS <pyproj.crs.CRS>` class to get
|
||||
information about the CRS.
|
||||
|
||||
@@ -14,22 +14,22 @@ 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 ``overlay`` function.
|
||||
the :func:`~geopandas.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:
|
||||
:class:`~geopandas.GeoDataFrame`, this operation is executed against every other shape in the other
|
||||
:class:`~geopandas.GeoDataFrame`:
|
||||
|
||||
.. image:: ../../_static/overlay_operations.png
|
||||
|
||||
**Source: QGIS Documentation**
|
||||
|
||||
(Note to users familiar with the *shapely* library: ``overlay`` can be thought
|
||||
(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 ``GeoSeries`` methods.)
|
||||
*shapely* set-operations are also available as :class:`~geopandas.GeoSeries` methods.)
|
||||
|
||||
|
||||
The different Overlay operations
|
||||
@@ -57,7 +57,7 @@ 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 ``overlay`` function will determine the set of all individual geometries
|
||||
The :func:`~geopandas.overlay` function 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.
|
||||
@@ -146,7 +146,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 ``overlay`` function, consider the following case in which one
|
||||
To illustrate the :func:`~geopandas.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.
|
||||
@@ -194,7 +194,7 @@ Changing the "how" option allows for different types of overlay operations. For
|
||||
keep_geom_type keyword
|
||||
----------------------
|
||||
|
||||
In default settings, ``overlay`` returns only geometries of the same geometry type as df1
|
||||
In default settings, :func:`~geopandas.overlay` returns only geometries of the same geometry type as df1
|
||||
(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 +205,7 @@ where two polygons intersects in a line or a point.
|
||||
More Examples
|
||||
-------------
|
||||
|
||||
A larger set of examples of the use of ``overlay`` can be found `here <http://nbviewer.jupyter.org/github/geopandas/geopandas/blob/master/examples/overlays.ipynb>`_
|
||||
A larger set of examples of the use of :func:`~geopandas.overlay` can be found `here <http://nbviewer.jupyter.org/github/geopandas/geopandas/blob/master/examples/overlays.ipynb>`_
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user