mirror of
https://github.com/wassname/geopandas.git
synced 2026-09-20 12:50:47 +08:00
DOC: documentation improvements (#1750)
* docstring changes * cx * notes * ci fix * skip check * updates based on the review * Update geopandas/base.py Co-authored-by: Flavin <flavinj@gmail.com> * typo Co-authored-by: Flavin <flavinj@gmail.com>
This commit is contained in:
Martin Fleischmann
co-authored by
Flavin
Flavin
parent
cfc732e610
commit
79aeefacd7
@@ -75,6 +75,14 @@ Spatial index
|
||||
GeoDataFrame.sindex
|
||||
GeoDataFrame.has_sindex
|
||||
|
||||
Indexing
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: api/
|
||||
|
||||
GeoDataFrame.cx
|
||||
|
||||
Interface
|
||||
---------
|
||||
|
||||
|
||||
@@ -154,6 +154,14 @@ Spatial index
|
||||
GeoSeries.sindex
|
||||
GeoSeries.has_sindex
|
||||
|
||||
Indexing
|
||||
--------
|
||||
|
||||
.. autosummary::
|
||||
:toctree: api/
|
||||
|
||||
GeoSeries.cx
|
||||
|
||||
Interface
|
||||
---------
|
||||
|
||||
|
||||
@@ -233,6 +233,9 @@ def points_from_xy(x, y, z=None, crs=None):
|
||||
"""
|
||||
Generate GeometryArray of shapely Point geometries from x, y(, z) coordinates.
|
||||
|
||||
In case of geographic coordinates, it is assumed that longitude is captured by
|
||||
``x`` coordinates and latitude by ``y``.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
x, y, z : iterable
|
||||
@@ -255,6 +258,16 @@ def points_from_xy(x, y, z=None, crs=None):
|
||||
>>> gdf = geopandas.GeoDataFrame(
|
||||
... df, geometry=geopandas.points_from_xy(df['x'], df['y']))
|
||||
|
||||
Having geographic coordinates:
|
||||
|
||||
>>> df = pd.DataFrame({'longitude': [-140, 0, 123], 'latitude': [-65, 1, 48]})
|
||||
>>> df
|
||||
longitude latitude
|
||||
0 -140 -65
|
||||
1 0 1
|
||||
2 123 48
|
||||
>>> geometry = geopandas.points_from_xy(df.longitude, df.latitude, crs="EPSG:4326")
|
||||
|
||||
Returns
|
||||
-------
|
||||
output : GeometryArray
|
||||
|
||||
+102
-7
@@ -87,7 +87,7 @@ class GeoPandasBase(object):
|
||||
@property
|
||||
def area(self):
|
||||
"""Returns a ``Series`` containing the area of each geometry in the
|
||||
``GeoSeries``.
|
||||
``GeoSeries`` expressed in the units of the CRS.
|
||||
|
||||
Examples
|
||||
--------
|
||||
@@ -117,6 +117,19 @@ class GeoPandasBase(object):
|
||||
3 0.0
|
||||
4 0.0
|
||||
dtype: float64
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.length : measure length
|
||||
|
||||
Notes
|
||||
-----
|
||||
Area may be invalid for a geographic CRS using degrees as units;
|
||||
use :meth:`GeoSeries.to_crs` to project geometries to a planar
|
||||
CRS before using this function.
|
||||
|
||||
Every operation in GeoPandas is planar, i.e. the potential third
|
||||
dimension is not taken into account.
|
||||
"""
|
||||
return _delegate_property("area", self)
|
||||
|
||||
@@ -147,6 +160,11 @@ class GeoPandasBase(object):
|
||||
Datum: World Geodetic System 1984
|
||||
- Ellipsoid: WGS 84
|
||||
- Prime Meridian: Greenwich
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.set_crs : assign CRS
|
||||
GeoSeries.to_crs : re-project to another CRS
|
||||
"""
|
||||
return self.geometry.values.crs
|
||||
|
||||
@@ -182,7 +200,11 @@ class GeoPandasBase(object):
|
||||
|
||||
@property
|
||||
def length(self):
|
||||
"""Returns a ``Series`` containing the length of each geometry.
|
||||
"""Returns a ``Series`` containing the length of each geometry
|
||||
expressed in the units of the CRS.
|
||||
|
||||
In the case of a (Multi)Polygon it measures the length
|
||||
of its exterior (i.e. perimeter).
|
||||
|
||||
Examples
|
||||
--------
|
||||
@@ -217,6 +239,20 @@ GeometryCollection
|
||||
4 0.000000
|
||||
5 16.180340
|
||||
dtype: float64
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.area : measure area of a polygon
|
||||
|
||||
Notes
|
||||
-----
|
||||
Length may be invalid for a geographic CRS using degrees as units;
|
||||
use :meth:`GeoSeries.to_crs` to project geometries to a planar
|
||||
CRS before using this function.
|
||||
|
||||
Every operation in GeoPandas is planar, i.e. the potential third
|
||||
dimension is not taken into account.
|
||||
|
||||
"""
|
||||
return _delegate_property("length", self)
|
||||
|
||||
@@ -321,6 +357,11 @@ GeometryCollection
|
||||
"""Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
|
||||
features that are closed.
|
||||
|
||||
When constructing a LinearRing, the sequence of coordinates may be
|
||||
explicitly closed by passing identical values in the first and last indices.
|
||||
Otherwise, the sequence will be implicitly closed by copying the first tuple
|
||||
to the last index.
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> from shapely.geometry import LineString, LinearRing
|
||||
@@ -337,11 +378,6 @@ GeometryCollection
|
||||
2 LINEARRING (0.00000 0.00000, 1.00000 1.00000, ...
|
||||
dtype: geometry
|
||||
|
||||
Note: When constructing a LinearRing, the sequence of coordinates may be
|
||||
explicitly closed by passing identical values in the first and last indices.
|
||||
Otherwise, the sequence will be implicitly closed by copying the first tuple
|
||||
to the last index.
|
||||
|
||||
>>> s.is_ring
|
||||
0 False
|
||||
1 True
|
||||
@@ -356,6 +392,11 @@ GeometryCollection
|
||||
"""Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
|
||||
features that have a z-component.
|
||||
|
||||
Notes
|
||||
------
|
||||
Every operation in GeoPandas is planar, i.e. the potential third
|
||||
dimension is not taken into account.
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> from shapely.geometry import Point
|
||||
@@ -409,6 +450,10 @@ GeometryCollection
|
||||
2 GEOMETRYCOLLECTION EMPTY
|
||||
dtype: geometry
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.exterior : outer boundary (without interior rings)
|
||||
|
||||
"""
|
||||
return _delegate_property("boundary", self)
|
||||
|
||||
@@ -441,6 +486,10 @@ GeometryCollection
|
||||
1 POINT (0.70711 0.50000)
|
||||
2 POINT (0.00000 0.00000)
|
||||
dtype: geometry
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.representative_point : point guaranteed to be within each geometry
|
||||
"""
|
||||
return _delegate_property("centroid", self)
|
||||
|
||||
@@ -483,6 +532,10 @@ GeometryCollection
|
||||
4 POINT (0.00000 0.00000)
|
||||
dtype: geometry
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.envelope : bounding rectangle geometry
|
||||
|
||||
"""
|
||||
return _delegate_property("convex_hull", self)
|
||||
|
||||
@@ -520,6 +573,10 @@ GeometryCollection
|
||||
2 POLYGON ((0.00000 0.00000, 1.00000 0.00000, 1....
|
||||
3 POINT (0.00000 0.00000)
|
||||
dtype: geometry
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.convex_hull : convex hull geometry
|
||||
"""
|
||||
return _delegate_property("envelope", self)
|
||||
|
||||
@@ -553,6 +610,11 @@ GeometryCollection
|
||||
1 LINEARRING (1.00000 0.00000, 2.00000 1.00000, ...
|
||||
2 None
|
||||
dtype: geometry
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.boundary : complete set-theoretic boundary
|
||||
GeoSeries.interiors : list of inner rings of each polygon
|
||||
"""
|
||||
# TODO: return empty geometry for non-polygons
|
||||
return _delegate_property("exterior", self)
|
||||
@@ -591,6 +653,10 @@ GeometryCollection
|
||||
0 [LINEARRING (1 1, 2 1, 1 2, 1 1), LINEARRING (...
|
||||
1 []
|
||||
dtype: object
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.exterior : outer boundary
|
||||
"""
|
||||
return _delegate_property("interiors", self)
|
||||
|
||||
@@ -620,6 +686,10 @@ GeometryCollection
|
||||
1 POINT (1.00000 1.00000)
|
||||
2 POINT (0.00000 0.00000)
|
||||
dtype: geometry
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries.centroid : geometric centroid
|
||||
"""
|
||||
return _delegate_geo_method("representative_point", self)
|
||||
|
||||
@@ -1392,6 +1462,31 @@ GeometryCollection
|
||||
``xmin``, ``xmax``, ``ymin``, and ``ymax`` can be provided, but input
|
||||
must include a comma separating x and y slices. That is, ``.cx[:, :]``
|
||||
will return the full series/frame, but ``.cx[:]`` is not implemented.
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> from shapely.geometry import LineString, Point
|
||||
>>> s = geopandas.GeoSeries(
|
||||
... [Point(0, 0), Point(1, 2), Point(3, 3), LineString([(0, 0), (3, 3)])]
|
||||
... )
|
||||
>>> s
|
||||
0 POINT (0.00000 0.00000)
|
||||
1 POINT (1.00000 2.00000)
|
||||
2 POINT (3.00000 3.00000)
|
||||
3 LINESTRING (0.00000 0.00000, 3.00000 3.00000)
|
||||
dtype: geometry
|
||||
|
||||
>>> s.cx[0:1, 0:1]
|
||||
0 POINT (0.00000 0.00000)
|
||||
3 LINESTRING (0.00000 0.00000, 3.00000 3.00000)
|
||||
dtype: geometry
|
||||
|
||||
>>> s.cx[:, 1:]
|
||||
1 POINT (1.00000 2.00000)
|
||||
2 POINT (3.00000 3.00000)
|
||||
3 LINESTRING (0.00000 0.00000, 3.00000 3.00000)
|
||||
dtype: geometry
|
||||
|
||||
"""
|
||||
return _CoordinateIndexer(self)
|
||||
|
||||
|
||||
@@ -18,6 +18,12 @@ def get_path(dataset):
|
||||
The name of the dataset. See ``geopandas.datasets.available`` for
|
||||
all options.
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> geopandas.datasets.get_path("naturalearth_lowres") # doctest: +SKIP
|
||||
'.../python3.8/site-packages/geopandas/datasets/\
|
||||
naturalearth_lowres/naturalearth_lowres.shp'
|
||||
|
||||
"""
|
||||
if dataset in _available_dir:
|
||||
return os.path.abspath(os.path.join(_module_path, dataset, dataset + ".shp"))
|
||||
|
||||
@@ -78,6 +78,10 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
col1 object
|
||||
geometry geometry
|
||||
dtype: object
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoSeries : Series object designed to store shapely geometry objects
|
||||
"""
|
||||
|
||||
_metadata = ["_crs", "_geometry_column_name"]
|
||||
@@ -230,10 +234,13 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
1 POLYGON ((4.00000 1.00000, 3.99037 0.80397, 3....
|
||||
Name: buffered, dtype: geometry
|
||||
|
||||
|
||||
Returns
|
||||
-------
|
||||
GeoDataFrame
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.rename_geometry : rename an active geometry column
|
||||
"""
|
||||
# Most of the code here is taken from DataFrame.set_index()
|
||||
if inplace:
|
||||
@@ -313,6 +320,10 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
Returns
|
||||
-------
|
||||
geodataframe : GeoDataFrame
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.set_geometry : set the active geometry
|
||||
"""
|
||||
geometry_col = self.geometry.name
|
||||
if col in self.columns:
|
||||
@@ -353,6 +364,11 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
- Ellipsoid: WGS 84
|
||||
- Prime Meridian: Greenwich
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.set_crs : assign CRS
|
||||
GeoDataFrame.to_crs : re-project to another CRS
|
||||
|
||||
"""
|
||||
return self._crs
|
||||
|
||||
@@ -468,7 +484,8 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
|
||||
See also
|
||||
--------
|
||||
read_file
|
||||
read_file : read file to GeoDataFame
|
||||
GeoDataFrame.to_file : write GeoDataFrame to file
|
||||
|
||||
"""
|
||||
return geopandas.io.file._read_file(filename, **kwargs)
|
||||
@@ -624,8 +641,7 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
|
||||
See also
|
||||
--------
|
||||
geopandas.read_postgis
|
||||
|
||||
geopandas.read_postgis : read PostGIS database to GeoDataFrame
|
||||
"""
|
||||
|
||||
df = geopandas.io.sql._read_postgis(
|
||||
@@ -682,6 +698,14 @@ class GeoDataFrame(GeoPandasBase, DataFrame):
|
||||
2.0]}}, {"id": "1", "type": "Feature", "properties": {"col1": "name2"}, "geometry"\
|
||||
: {"type": "Point", "coordinates": [2.0, 1.0]}}]}'
|
||||
|
||||
Alternatively, you can write GeoJSON to file:
|
||||
|
||||
>>> gdf.to_file(path, driver="GeoJSON") # doctest: +SKIP
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.to_file : write GeoDataFrame to file
|
||||
|
||||
"""
|
||||
return json.dumps(self._to_geo(na=na, show_bbox=show_bbox), **kwargs)
|
||||
|
||||
@@ -856,6 +880,11 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
--------
|
||||
|
||||
>>> gdf.to_parquet('data.parquet') # doctest: +SKIP
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.to_feather : write GeoDataFrame to feather
|
||||
GeoDataFrame.to_file : write GeoDataFrame to file
|
||||
"""
|
||||
|
||||
from geopandas.io.arrow import _to_parquet
|
||||
@@ -899,6 +928,11 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
--------
|
||||
|
||||
>>> gdf.to_feather('data.feather') # doctest: +SKIP
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.to_parquet : write GeoDataFrame to parquet
|
||||
GeoDataFrame.to_file : write GeoDataFrame to file
|
||||
"""
|
||||
|
||||
from geopandas.io.arrow import _to_feather
|
||||
@@ -948,6 +982,9 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
See Also
|
||||
--------
|
||||
GeoSeries.to_file
|
||||
GeoDataFrame.to_postgis : write GeoDataFrame to PostGIS database
|
||||
GeoDataFrame.to_parquet : write GeoDataFrame to parquet
|
||||
GeoDataFrame.to_feather : write GeoDataFrame to feather
|
||||
|
||||
Examples
|
||||
--------
|
||||
@@ -957,6 +994,10 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
>>> gdf.to_file('dataframe.gpkg', driver='GPKG', layer='name') # doctest: +SKIP
|
||||
|
||||
>>> gdf.to_file('dataframe.geojson', driver='GeoJSON') # doctest: +SKIP
|
||||
|
||||
With selected drivers you can also append to a file with `mode="a"`:
|
||||
|
||||
>>> gdf.to_file('dataframe.shp', mode="a") # doctest: +SKIP
|
||||
"""
|
||||
from geopandas.io.file import _to_file
|
||||
|
||||
@@ -1026,6 +1067,11 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
|
||||
Without ``allow_override=True``, ``set_crs`` returns an error if you try to
|
||||
override CRS.
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.to_crs : re-project to another CRS
|
||||
|
||||
"""
|
||||
if not inplace:
|
||||
df = self.copy()
|
||||
@@ -1107,6 +1153,10 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
Datum: World Geodetic System 1984
|
||||
- Ellipsoid: WGS 84
|
||||
- Prime Meridian: Greenwich
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.set_crs : assign CRS without re-projection
|
||||
"""
|
||||
if inplace:
|
||||
df = self
|
||||
@@ -1302,6 +1352,10 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
name1 MULTIPOINT (0.00000 1.00000, 1.00000 2.00000)
|
||||
name2 POINT (2.00000 1.00000)
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.explode : explode muti-part geometries into single geometries
|
||||
|
||||
"""
|
||||
|
||||
if by is None:
|
||||
@@ -1375,6 +1429,11 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
1 name1 POINT (3.00000 4.00000)
|
||||
1 0 name2 POINT (2.00000 1.00000)
|
||||
1 name2 POINT (0.00000 0.00000)
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.dissolve : dissolve geometries into a single observation.
|
||||
|
||||
"""
|
||||
|
||||
# If no column is specified then default to the active geometry column
|
||||
@@ -1487,6 +1546,12 @@ box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)}
|
||||
>>> engine = create_engine("postgres://myusername:mypassword@myhost:5432\
|
||||
/mydatabase") # doctest: +SKIP
|
||||
>>> gdf.to_postgis("my_table", engine) # doctest: +SKIP
|
||||
|
||||
See also
|
||||
--------
|
||||
GeoDataFrame.to_file : write GeoDataFrame to file
|
||||
read_postgis : read PostGIS database to GeoDataFrame
|
||||
|
||||
"""
|
||||
geopandas.io.sql._write_postgis(
|
||||
self, name, con, schema, if_exists, index, index_label, chunksize, dtype
|
||||
|
||||
+22
-1
@@ -320,6 +320,10 @@ class GeoSeries(GeoPandasBase, Series):
|
||||
3 MULTIPOLYGON (((981219.056 188655.316, 980940....
|
||||
4 MULTIPOLYGON (((1012821.806 229228.265, 101278...
|
||||
Name: geometry, dtype: geometry
|
||||
|
||||
See Also
|
||||
--------
|
||||
read_file : read file to GeoDataFame
|
||||
"""
|
||||
from geopandas import GeoDataFrame
|
||||
|
||||
@@ -383,7 +387,8 @@ class GeoSeries(GeoPandasBase, Series):
|
||||
|
||||
See Also
|
||||
--------
|
||||
GeoDataFrame.to_file
|
||||
GeoDataFrame.to_file : write GeoDataFrame to file
|
||||
read_file : read file to GeoDataFame
|
||||
|
||||
Examples
|
||||
--------
|
||||
@@ -602,6 +607,10 @@ class GeoSeries(GeoPandasBase, Series):
|
||||
1 POLYGON ((0.00000 1.00000, 2.00000 1.00000, 1....
|
||||
2 POLYGON ((0.00000 0.00000, -1.00000 1.00000, 0...
|
||||
dtype: geometry
|
||||
|
||||
See Also
|
||||
--------
|
||||
GeoSeries.isna : detect missing values
|
||||
"""
|
||||
if value is None:
|
||||
value = BaseGeometry()
|
||||
@@ -786,6 +795,10 @@ class GeoSeries(GeoPandasBase, Series):
|
||||
Without ``allow_override=True``, ``set_crs`` returns an error if you try to
|
||||
override CRS.
|
||||
|
||||
See Also
|
||||
--------
|
||||
GeoSeries.to_crs : re-project to another CRS
|
||||
|
||||
"""
|
||||
if crs is not None:
|
||||
crs = CRS.from_user_input(crs)
|
||||
@@ -879,6 +892,10 @@ class GeoSeries(GeoPandasBase, Series):
|
||||
- Ellipsoid: WGS 84
|
||||
- Prime Meridian: Greenwich
|
||||
|
||||
See Also
|
||||
--------
|
||||
GeoSeries.set_crs : assign CRS
|
||||
|
||||
"""
|
||||
if self.crs is None:
|
||||
raise ValueError(
|
||||
@@ -1005,6 +1022,10 @@ operties": {}, "geometry": {"type": "Point", "coordinates": [1.0, 1.0]}, "bbox":
|
||||
: "Point", "coordinates": [2.0, 2.0]}, "bbox": [2.0, 2.0, 2.0, 2.0]}, {"id": "2", "typ\
|
||||
e": "Feature", "properties": {}, "geometry": {"type": "Point", "coordinates": [3.0, 3.\
|
||||
0]}, "bbox": [3.0, 3.0, 3.0, 3.0]}], "bbox": [1.0, 1.0, 3.0, 3.0]}'
|
||||
|
||||
See Also
|
||||
--------
|
||||
GeoSeries.to_file : write GeoSeries to file
|
||||
"""
|
||||
return json.dumps(self.__geo_interface__, **kwargs)
|
||||
|
||||
|
||||
@@ -587,6 +587,27 @@ def plot_dataframe(
|
||||
-------
|
||||
ax : matplotlib axes instance
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> df = geopandas.read_file(geopandas.datasets.get_path("naturalearth_lowres"))
|
||||
>>> df.head() # doctest: +SKIP
|
||||
pop_est continent name iso_a3 \
|
||||
gdp_md_est geometry
|
||||
0 920938 Oceania Fiji FJI 8374.0 MULTIPOLY\
|
||||
GON (((180.00000 -16.06713, 180.00000...
|
||||
1 53950935 Africa Tanzania TZA 150600.0 POLYGON (\
|
||||
(33.90371 -0.95000, 34.07262 -1.05982...
|
||||
2 603253 Africa W. Sahara ESH 906.5 POLYGON (\
|
||||
(-8.66559 27.65643, -8.66512 27.58948...
|
||||
3 35623680 North America Canada CAN 1674000.0 MULTIPOLY\
|
||||
GON (((-122.84000 49.00000, -122.9742...
|
||||
4 326625791 North America United States of America USA 18560000.0 MULTIPOLY\
|
||||
GON (((-122.84000 49.00000, -120.0000...
|
||||
|
||||
>>> df.plot("pop_est", cmap="Blues") # doctest: +SKIP
|
||||
|
||||
See the User Guide page :doc:`../../user_guide/mapping` for details.
|
||||
|
||||
"""
|
||||
if "colormap" in style_kwds:
|
||||
warnings.warn(
|
||||
|
||||
@@ -106,7 +106,6 @@ def clip(gdf, mask, keep_geom_type=False):
|
||||
--------
|
||||
Clip points (global cities) with a polygon (the South American continent):
|
||||
|
||||
>>> import geopandas
|
||||
>>> world = geopandas.read_file(
|
||||
... geopandas.datasets.get_path('naturalearth_lowres'))
|
||||
>>> south_america = world[world['continent'] == "South America"]
|
||||
@@ -114,6 +113,7 @@ def clip(gdf, mask, keep_geom_type=False):
|
||||
... geopandas.datasets.get_path('naturalearth_cities'))
|
||||
>>> capitals.shape
|
||||
(202, 2)
|
||||
|
||||
>>> sa_capitals = geopandas.clip(capitals, south_america)
|
||||
>>> sa_capitals.shape
|
||||
(12, 2)
|
||||
|
||||
@@ -145,6 +145,8 @@ def overlay(df1, df2, how="intersection", keep_geom_type=True):
|
||||
combination of (Multi)LineString and LinearRing shapes.
|
||||
Implements several methods that are all effectively subsets of the union.
|
||||
|
||||
See the User Guide page :doc:`../../user_guide/set_operations` for details.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
df1 : GeoDataFrame
|
||||
@@ -162,6 +164,60 @@ def overlay(df1, df2, how="intersection", keep_geom_type=True):
|
||||
GeoDataFrame with new set of polygons and attributes
|
||||
resulting from the overlay
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> from shapely.geometry import Polygon
|
||||
>>> polys1 = geopandas.GeoSeries([Polygon([(0,0), (2,0), (2,2), (0,2)]),
|
||||
... Polygon([(2,2), (4,2), (4,4), (2,4)])])
|
||||
>>> polys2 = geopandas.GeoSeries([Polygon([(1,1), (3,1), (3,3), (1,3)]),
|
||||
... Polygon([(3,3), (5,3), (5,5), (3,5)])])
|
||||
>>> df1 = geopandas.GeoDataFrame({'geometry': polys1, 'df1_data':[1,2]})
|
||||
>>> df2 = geopandas.GeoDataFrame({'geometry': polys2, 'df2_data':[1,2]})
|
||||
|
||||
>>> geopandas.overlay(df1, df2, how='union')
|
||||
df1_data df2_data geometry
|
||||
0 1.0 1.0 POLYGON ((1.00000 2.00000, 2.00000 2.00000, 2....
|
||||
1 2.0 1.0 POLYGON ((2.00000 2.00000, 2.00000 3.00000, 3....
|
||||
2 2.0 2.0 POLYGON ((3.00000 4.00000, 4.00000 4.00000, 4....
|
||||
3 1.0 NaN POLYGON ((0.00000 0.00000, 0.00000 2.00000, 1....
|
||||
4 2.0 NaN MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...
|
||||
5 NaN 1.0 MULTIPOLYGON (((2.00000 2.00000, 3.00000 2.000...
|
||||
6 NaN 2.0 POLYGON ((3.00000 4.00000, 3.00000 5.00000, 5....
|
||||
|
||||
>>> geopandas.overlay(df1, df2, how='intersection')
|
||||
df1_data df2_data geometry
|
||||
0 1 1 POLYGON ((1.00000 2.00000, 2.00000 2.00000, 2....
|
||||
1 2 1 POLYGON ((2.00000 2.00000, 2.00000 3.00000, 3....
|
||||
2 2 2 POLYGON ((3.00000 4.00000, 4.00000 4.00000, 4....
|
||||
|
||||
>>> geopandas.overlay(df1, df2, how='symmetric_difference')
|
||||
df1_data df2_data geometry
|
||||
0 1.0 NaN POLYGON ((0.00000 0.00000, 0.00000 2.00000, 1....
|
||||
1 2.0 NaN MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...
|
||||
2 NaN 1.0 MULTIPOLYGON (((2.00000 2.00000, 3.00000 2.000...
|
||||
3 NaN 2.0 POLYGON ((3.00000 4.00000, 3.00000 5.00000, 5....
|
||||
|
||||
>>> geopandas.overlay(df1, df2, how='difference')
|
||||
geometry df1_data
|
||||
0 POLYGON ((0.00000 0.00000, 0.00000 2.00000, 1.... 1
|
||||
1 MULTIPOLYGON (((2.00000 3.00000, 2.00000 4.000... 2
|
||||
|
||||
>>> geopandas.overlay(df1, df2, how='identity')
|
||||
df1_data df2_data geometry
|
||||
0 1.0 1.0 POLYGON ((1.00000 2.00000, 2.00000 2.00000, 2....
|
||||
1 2.0 1.0 POLYGON ((2.00000 2.00000, 2.00000 3.00000, 3....
|
||||
2 2.0 2.0 POLYGON ((3.00000 4.00000, 4.00000 4.00000, 4....
|
||||
3 1.0 NaN POLYGON ((0.00000 0.00000, 0.00000 2.00000, 1....
|
||||
4 2.0 NaN MULTIPOLYGON (((3.00000 3.00000, 4.00000 3.000...
|
||||
|
||||
See also
|
||||
--------
|
||||
sjoin : spatial join
|
||||
|
||||
Notes
|
||||
------
|
||||
Every operation in GeoPandas is planar, i.e. the potential third
|
||||
dimension is not taken into account.
|
||||
"""
|
||||
# Allowed operations
|
||||
allowed_hows = [
|
||||
|
||||
@@ -11,6 +11,9 @@ def sjoin(
|
||||
):
|
||||
"""Spatial join of two GeoDataFrames.
|
||||
|
||||
See the User Guide page :doc:`../../user_guide/mergingdata` for details.
|
||||
|
||||
|
||||
Parameters
|
||||
----------
|
||||
left_df, right_df : GeoDataFrames
|
||||
@@ -23,13 +26,63 @@ def sjoin(
|
||||
left_df geometry column
|
||||
op : string, default 'intersects'
|
||||
Binary predicate. Valid values are determined by the spatial index used.
|
||||
You can check the valid values in `left_df` or `right_df` as
|
||||
`left_df.sindex.valid_query_predicates` or
|
||||
`right_df.sindex.valid_query_predicates`
|
||||
You can check the valid values in left_df or right_df as
|
||||
``left_df.sindex.valid_query_predicates`` or
|
||||
``right_df.sindex.valid_query_predicates``
|
||||
lsuffix : string, default 'left'
|
||||
Suffix to apply to overlapping column names (left GeoDataFrame).
|
||||
rsuffix : string, default 'right'
|
||||
Suffix to apply to overlapping column names (right GeoDataFrame).
|
||||
|
||||
Examples
|
||||
--------
|
||||
>>> countries = geopandas.read_file(geopandas.datasets.get_\
|
||||
path("naturalearth_lowres"))
|
||||
>>> cities = geopandas.read_file(geopandas.datasets.get_path("naturalearth_cities"))
|
||||
>>> countries.head() # doctest: +SKIP
|
||||
pop_est continent name \
|
||||
iso_a3 gdp_md_est geometry
|
||||
0 920938 Oceania Fiji FJI 8374.0 MULTIPOLY\
|
||||
GON (((180.00000 -16.06713, 180.00000...
|
||||
1 53950935 Africa Tanzania TZA 150600.0 POLYGON (\
|
||||
(33.90371 -0.95000, 34.07262 -1.05982...
|
||||
2 603253 Africa W. Sahara ESH 906.5 POLYGON (\
|
||||
(-8.66559 27.65643, -8.66512 27.58948...
|
||||
3 35623680 North America Canada CAN 1674000.0 MULTIPOLY\
|
||||
GON (((-122.84000 49.00000, -122.9742...
|
||||
4 326625791 North America United States of America USA 18560000.0 MULTIPOLY\
|
||||
GON (((-122.84000 49.00000, -120.0000...
|
||||
>>> cities.head()
|
||||
name geometry
|
||||
0 Vatican City POINT (12.45339 41.90328)
|
||||
1 San Marino POINT (12.44177 43.93610)
|
||||
2 Vaduz POINT (9.51667 47.13372)
|
||||
3 Luxembourg POINT (6.13000 49.61166)
|
||||
4 Palikir POINT (158.14997 6.91664)
|
||||
|
||||
>>> cities_w_country_data = geopandas.sjoin(cities, countries)
|
||||
>>> cities_w_country_data.head() # doctest: +SKIP
|
||||
name_left geometry index_right pop_est continent name_\
|
||||
right iso_a3 gdp_md_est
|
||||
0 Vatican City POINT (12.45339 41.90328) 141 62137802 Europe \
|
||||
Italy ITA 2221000.0
|
||||
1 San Marino POINT (12.44177 43.93610) 141 62137802 Europe \
|
||||
Italy ITA 2221000.0
|
||||
192 Rome POINT (12.48131 41.89790) 141 62137802 Europe \
|
||||
Italy ITA 2221000.0
|
||||
2 Vaduz POINT (9.51667 47.13372) 114 8754413 Europe Au\
|
||||
stria AUT 416600.0
|
||||
184 Vienna POINT (16.36469 48.20196) 114 8754413 Europe Au\
|
||||
stria AUT 416600.0
|
||||
|
||||
See also
|
||||
--------
|
||||
overlay : overlay operation resulting in a new geometry
|
||||
|
||||
Notes
|
||||
------
|
||||
Every operation in GeoPandas is planar, i.e. the potential third
|
||||
dimension is not taken into account.
|
||||
"""
|
||||
_basic_checks(left_df, right_df, how, lsuffix, rsuffix)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user