diff --git a/doc/source/docs/reference/geodataframe.rst b/doc/source/docs/reference/geodataframe.rst index 71c1a85..c6988f8 100644 --- a/doc/source/docs/reference/geodataframe.rst +++ b/doc/source/docs/reference/geodataframe.rst @@ -75,6 +75,14 @@ Spatial index GeoDataFrame.sindex GeoDataFrame.has_sindex +Indexing +-------- + +.. autosummary:: + :toctree: api/ + + GeoDataFrame.cx + Interface --------- diff --git a/doc/source/docs/reference/geoseries.rst b/doc/source/docs/reference/geoseries.rst index a657d21..44a23fe 100644 --- a/doc/source/docs/reference/geoseries.rst +++ b/doc/source/docs/reference/geoseries.rst @@ -154,6 +154,14 @@ Spatial index GeoSeries.sindex GeoSeries.has_sindex +Indexing +-------- + +.. autosummary:: + :toctree: api/ + + GeoSeries.cx + Interface --------- diff --git a/geopandas/array.py b/geopandas/array.py index ea2accc..ea0eb72 100644 --- a/geopandas/array.py +++ b/geopandas/array.py @@ -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 diff --git a/geopandas/base.py b/geopandas/base.py index f9401c0..b2e2802 100644 --- a/geopandas/base.py +++ b/geopandas/base.py @@ -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) diff --git a/geopandas/datasets/__init__.py b/geopandas/datasets/__init__.py index a592b56..b56d202 100644 --- a/geopandas/datasets/__init__.py +++ b/geopandas/datasets/__init__.py @@ -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")) diff --git a/geopandas/geodataframe.py b/geopandas/geodataframe.py index d7c79b2..09188ef 100644 --- a/geopandas/geodataframe.py +++ b/geopandas/geodataframe.py @@ -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 diff --git a/geopandas/geoseries.py b/geopandas/geoseries.py index e9381a9..793cf7c 100644 --- a/geopandas/geoseries.py +++ b/geopandas/geoseries.py @@ -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) diff --git a/geopandas/plotting.py b/geopandas/plotting.py index c176569..275175e 100644 --- a/geopandas/plotting.py +++ b/geopandas/plotting.py @@ -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( diff --git a/geopandas/tools/clip.py b/geopandas/tools/clip.py index 6e677b9..12d41c6 100644 --- a/geopandas/tools/clip.py +++ b/geopandas/tools/clip.py @@ -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) diff --git a/geopandas/tools/overlay.py b/geopandas/tools/overlay.py index 7d1d97a..d3c0bf8 100644 --- a/geopandas/tools/overlay.py +++ b/geopandas/tools/overlay.py @@ -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 = [ diff --git a/geopandas/tools/sjoin.py b/geopandas/tools/sjoin.py index 067fc79..8e2aea6 100644 --- a/geopandas/tools/sjoin.py +++ b/geopandas/tools/sjoin.py @@ -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)