diff --git a/doc/source/conf.py b/doc/source/conf.py index cf3a8e9..e85390c 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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", ), -} \ No newline at end of file + "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" + ) +} diff --git a/doc/source/docs/user_guide/aggregation_with_dissolve.rst b/doc/source/docs/user_guide/aggregation_with_dissolve.rst index ea5f2ed..f6952dd 100644 --- a/doc/source/docs/user_guide/aggregation_with_dissolve.rst +++ b/doc/source/docs/user_guide/aggregation_with_dissolve.rst @@ -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 `, 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 `. .. 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 ` including: * 'first' * 'last' diff --git a/doc/source/docs/user_guide/data_structures.rst b/doc/source/docs/user_guide/data_structures.rst index 256152b..f50f847 100644 --- a/doc/source/docs/user_guide/data_structures.rst +++ b/doc/source/docs/user_guide/data_structures.rst @@ -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 ` @@ -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 ` page and for geocoding with are described in :doc:`Geocoding `. +However, :class:`GeoDataFrames ` also have a few extra methods for input and output which are described on the :doc:`Input and Output ` page and for geocoding with are described in :doc:`Geocoding `. .. ipython:: python diff --git a/doc/source/docs/user_guide/geocoding.rst b/doc/source/docs/user_guide/geocoding.rst index c573f59..a0131d6 100644 --- a/doc/source/docs/user_guide/geocoding.rst +++ b/doc/source/docs/user_guide/geocoding.rst @@ -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 `__ 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 ` 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: diff --git a/doc/source/docs/user_guide/geometric_manipulations.rst b/doc/source/docs/user_guide/geometric_manipulations.rst index 3d51f8f..525833b 100644 --- a/doc/source/docs/user_guide/geometric_manipulations.rst +++ b/doc/source/docs/user_guide/geometric_manipulations.rst @@ -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``. diff --git a/doc/source/docs/user_guide/indexing.rst b/doc/source/docs/user_guide/indexing.rst index bb9f90a..971e501 100644 --- a/doc/source/docs/user_guide/indexing.rst +++ b/doc/source/docs/user_guide/indexing.rst @@ -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)); - diff --git a/doc/source/docs/user_guide/io.rst b/doc/source/docs/user_guide/io.rst index b5826b3..5d4ee9e 100644 --- a/doc/source/docs/user_guide/io.rst +++ b/doc/source/docs/user_guide/io.rst @@ -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 `_:: 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) diff --git a/doc/source/docs/user_guide/mapping.rst b/doc/source/docs/user_guide/mapping.rst index cede0c6..bb575e8 100644 --- a/doc/source/docs/user_guide/mapping.rst +++ b/doc/source/docs/user_guide/mapping.rst @@ -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 `_ in ``matplotlib`` (or `style options that work for lines `_) can be passed to the ``plot()`` method. +Note that in general, any options one can pass to `pyplot `_ in matplotlib_ (or `style options that work for lines `_) 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 `_): +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 `_): .. ipython:: python diff --git a/doc/source/docs/user_guide/mergingdata.rst b/doc/source/docs/user_guide/mergingdata.rst index a90e3e2..6edc2d7 100644 --- a/doc/source/docs/user_guide/mergingdata.rst +++ b/doc/source/docs/user_guide/mergingdata.rst @@ -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. diff --git a/doc/source/docs/user_guide/missing_empty.rst b/doc/source/docs/user_guide/missing_empty.rst index 39905d0..84f6813 100644 --- a/doc/source/docs/user_guide/missing_empty.rst +++ b/doc/source/docs/user_guide/missing_empty.rst @@ -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. diff --git a/doc/source/docs/user_guide/projections.rst b/doc/source/docs/user_guide/projections.rst index 4eb1530..b3f4c32 100644 --- a/doc/source/docs/user_guide/projections.rst +++ b/doc/source/docs/user_guide/projections.rst @@ -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 ` - 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 `, 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 `__ for more on -the ``pyproj.CRS`` object. +the :class:`pyproj.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 ` object, a WKT string, a PROJ JSON string, etc. +Anything that is accepted by :meth:`pyproj.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 ` 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 ` 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 ` class to get information about the CRS. diff --git a/doc/source/docs/user_guide/set_operations.rst b/doc/source/docs/user_guide/set_operations.rst index bb01c87..0734dd7 100644 --- a/doc/source/docs/user_guide/set_operations.rst +++ b/doc/source/docs/user_guide/set_operations.rst @@ -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 `_ +A larger set of examples of the use of :func:`~geopandas.overlay` can be found `here `_