diff --git a/doc/source/conf.py b/doc/source/conf.py index c31a869..2be0bc0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -35,6 +35,7 @@ extensions = [ "sphinx.ext.autodoc", "myst_nb", "numpydoc", + 'sphinx_toggleprompt', ] # continue doc build and only print warnings/errors in examples diff --git a/doc/source/docs/reference/geodataframe.rst b/doc/source/docs/reference/geodataframe.rst index 60c94c2..e1ce804 100644 --- a/doc/source/docs/reference/geodataframe.rst +++ b/doc/source/docs/reference/geodataframe.rst @@ -80,6 +80,7 @@ Interface :toctree: api/ GeoDataFrame.__geo_interface__ + GeoDataFrame.iterfeatures All pandas ``DataFrame`` methods are also available, although they may not operate in a meaningful way on the ``geometry`` column. All methods diff --git a/geopandas/base.py b/geopandas/base.py index 4093487..077b704 100644 --- a/geopandas/base.py +++ b/geopandas/base.py @@ -94,7 +94,37 @@ class GeoPandasBase(object): @property def area(self): """Returns a ``Series`` containing the area of each geometry in the - ``GeoSeries``.""" + ``GeoSeries``. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, Point + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... Polygon([(10, 0), (10, 5), (0, 0)]), + ... Polygon([(0, 0), (2, 2), (2, 0)]), + ... LineString([(0, 0), (1, 1), (0, 1)]), + ... Point(0, 1) + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 POLYGON ((10.00000 0.00000, 10.00000 5.00000, ... + 2 POLYGON ((0.00000 0.00000, 2.00000 2.00000, 2.... + 3 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 4 POINT (0.00000 1.00000) + dtype: geometry + + >>> s.area + 0 0.5 + 1 25.0 + 2 2.0 + 3 0.0 + 4 0.0 + dtype: float64 + """ return _delegate_property("area", self) @property @@ -108,6 +138,22 @@ class GeoPandasBase(object): can be anything accepted by :meth:`pyproj.CRS.from_user_input() `, such as an authority string (eg "EPSG:4326") or a WKT string. + + Examples + -------- + + >>> s.crs + + Name: WGS 84 + Axis Info [ellipsoidal]: + - Lat[north]: Geodetic latitude (degree) + - Lon[east]: Geodetic longitude (degree) + Area of Use: + - name: World + - bounds: (-180.0, -90.0, 180.0, 90.0) + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich """ return self.geometry.values.crs @@ -143,13 +189,79 @@ 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. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, MultiLineString, Point, \ +GeometryCollection + >>> s = geopandas.GeoSeries( + ... [ + ... LineString([(0, 0), (1, 1), (0, 1)]), + ... LineString([(10, 0), (10, 5), (0, 0)]), + ... MultiLineString([((0, 0), (1, 0)), ((-1, 0), (1, 0))]), + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... Point(0, 1), + ... GeometryCollection([Point(1, 0), LineString([(10, 0), (10, 5), (0,\ + 0)])]) + ... ] + ... ) + >>> s + 0 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 1 LINESTRING (10.00000 0.00000, 10.00000 5.00000... + 2 MULTILINESTRING ((0.00000 0.00000, 1.00000 1.0... + 3 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 4 POINT (0.00000 1.00000) + 5 GEOMETRYCOLLECTION (POINT (1.00000 0.00000), L... + dtype: geometry + + >>> s.length + 0 2.414214 + 1 16.180340 + 2 3.000000 + 3 3.414214 + 4 0.000000 + 5 16.180340 + dtype: float64 + """ return _delegate_property("length", self) @property def is_valid(self): """Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for - geometries that are valid.""" + geometries that are valid. + + Examples + -------- + + An example with one invalid polygon (a bowtie geometry crossing itself) + and one missing geometry: + + >>> from shapely.geometry import Polygon + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... Polygon([(0,0), (1, 1), (1, 0), (0, 1)]), # bowtie geometry + ... Polygon([(0, 0), (2, 2), (2, 0)]), + ... None + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 1.... + 2 POLYGON ((0.00000 0.00000, 2.00000 2.00000, 2.... + 3 None + dtype: geometry + + >>> s.is_valid + 0 True + 1 False + 2 True + 3 False + dtype: bool + + """ return _delegate_property("is_valid", self) @property @@ -189,19 +301,87 @@ class GeoPandasBase(object): geometries that do not cross themselves. This is meaningful only for `LineStrings` and `LinearRings`. + + Examples + -------- + >>> from shapely.geometry import LineString + >>> s = geopandas.GeoSeries( + ... [ + ... LineString([(0, 0), (1, 1), (1, -1), (0, 1)]), + ... LineString([(0, 0), (1, 1), (1, -1)]), + ... ] + ... ) + >>> s + 0 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + dtype: geometry + + >>> s.is_simple + 0 False + 1 True + dtype: bool """ return _delegate_property("is_simple", self) @property def is_ring(self): """Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for - features that are closed.""" + features that are closed. + + Examples + -------- + >>> from shapely.geometry import LineString, LinearRing + >>> s = geopandas.GeoSeries( + ... [ + ... LineString([(0, 0), (1, 1), (1, -1)]), + ... LineString([(0, 0), (1, 1), (1, -1), (0, 0)]), + ... LinearRing([(0, 0), (1, 1), (1, -1)]), + ... ] + ... ) + >>> s + 0 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 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 + 2 True + dtype: bool + + """ return _delegate_property("is_ring", self) @property def has_z(self): """Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for - features that have a z-component.""" + features that have a z-component. + + Examples + -------- + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries( + ... [ + ... Point(0, 1), + ... Point(0, 1, 2), + ... ] + ... ) + >>> s + 0 POINT (0.00000 1.00000) + 1 POINT Z (0.00000 1.00000 2.00000) + dtype: geometry + + >>> s.has_z + 0 False + 1 True + dtype: bool + """ return _delegate_property("has_z", self) # @@ -211,13 +391,64 @@ class GeoPandasBase(object): @property def boundary(self): """Returns a ``GeoSeries`` of lower dimensional objects representing - each geometries's set-theoretic `boundary`.""" + each geometries's set-theoretic `boundary`. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, Point + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... LineString([(0, 0), (1, 1), (1, 0)]), + ... Point(0, 0), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 2 POINT (0.00000 0.00000) + dtype: geometry + + >>> s.boundary + 0 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 1 MULTIPOINT (0.00000 0.00000, 1.00000 0.00000) + 2 GEOMETRYCOLLECTION EMPTY + dtype: geometry + + """ return _delegate_property("boundary", self) @property def centroid(self): """Returns a ``GeoSeries`` of points representing the centroid of each - geometry.""" + geometry. + + Note that centroid does not have to be on or within original geometry. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, Point + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... LineString([(0, 0), (1, 1), (1, 0)]), + ... Point(0, 0), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 2 POINT (0.00000 0.00000) + dtype: geometry + + >>> s.centroid + 0 POINT (0.33333 0.66667) + 1 POINT (0.70711 0.50000) + 2 POINT (0.00000 0.00000) + dtype: geometry + """ return _delegate_property("centroid", self) @property @@ -228,7 +459,37 @@ class GeoPandasBase(object): The convex hull of a geometry is the smallest convex `Polygon` containing all the points in each geometry, unless the number of points in the geometric object is less than three. For two points, the convex - hull collapses to a `LineString`; for 1, a `Point`.""" + hull collapses to a `LineString`; for 1, a `Point`. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, Point, MultiPoint + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... LineString([(0, 0), (1, 1), (1, 0)]), + ... MultiPoint([(0, 0), (1, 1), (0, 1), (1, 0), (0.5, 0.5)]), + ... MultiPoint([(0, 0), (1, 1)]), + ... Point(0, 0), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 2 MULTIPOINT (0.00000 0.00000, 1.00000 1.00000, ... + 3 MULTIPOINT (0.00000 0.00000, 1.00000 1.00000) + 4 POINT (0.00000 0.00000) + + >>> s.convex_hull + 0 POLYGON ((0.00000 0.00000, 0.00000 1.00000, 1.... + 1 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 1.... + 2 POLYGON ((0.00000 0.00000, 0.00000 1.00000, 1.... + 3 LINESTRING (0.00000 0.00000, 1.00000 1.00000) + 4 POINT (0.00000 0.00000) + dtype: geometry + + """ return _delegate_property("convex_hull", self) @property @@ -238,7 +499,34 @@ class GeoPandasBase(object): The envelope of a geometry is the bounding rectangle. That is, the point or smallest rectangular polygon (with sides parallel to the - coordinate axes) that contains the geometry.""" + coordinate axes) that contains the geometry. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, Point, MultiPoint + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... LineString([(0, 0), (1, 1), (1, 0)]), + ... MultiPoint([(0, 0), (1, 1)]), + ... Point(0, 0), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 2 MULTIPOINT (0.00000 0.00000, 1.00000 1.00000) + 3 POINT (0.00000 0.00000) + dtype: geometry + + >>> s.envelope + 0 POLYGON ((0.00000 0.00000, 1.00000 0.00000, 1.... + 1 POLYGON ((0.00000 0.00000, 1.00000 0.00000, 1.... + 2 POLYGON ((0.00000 0.00000, 1.00000 0.00000, 1.... + 3 POINT (0.00000 0.00000) + dtype: geometry + """ return _delegate_property("envelope", self) @property @@ -246,7 +534,31 @@ class GeoPandasBase(object): """Returns a ``GeoSeries`` of LinearRings representing the outer boundary of each polygon in the GeoSeries. - Applies to GeoSeries containing only Polygons. + Applies to GeoSeries containing only Polygons. Returns ``None``` for + other geometry types. + + Examples + -------- + + >>> from shapely.geometry import Polygon, Point + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... Polygon([(1, 0), (2, 1), (0, 0)]), + ... Point(0, 1) + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 POLYGON ((1.00000 0.00000, 2.00000 1.00000, 0.... + 2 POINT (0.00000 1.00000) + dtype: geometry + + >>> s.exterior + 0 LINEARRING (0.00000 0.00000, 1.00000 1.00000, ... + 1 LINEARRING (1.00000 0.00000, 2.00000 1.00000, ... + 2 None + dtype: geometry """ # TODO: return empty geometry for non-polygons return _delegate_property("exterior", self) @@ -262,12 +574,58 @@ class GeoPandasBase(object): ---------- inner_rings: Series of List Inner rings of each polygon in the GeoSeries. + + Examples + -------- + + >>> from shapely.geometry import Polygon + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon( + ... [(0, 0), (0, 5), (5, 5), (5, 0)], + ... [[(1, 1), (2, 1), (1, 2)], [(1, 4), (2, 4), (2, 3)]], + ... ), + ... Polygon([(1, 0), (2, 1), (0, 0)]), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 0.00000 5.00000, 5.... + 1 POLYGON ((1.00000 0.00000, 2.00000 1.00000, 0.... + dtype: geometry + + >>> s.interiors + 0 [LINEARRING (1 1, 2 1, 1 2, 1 1), LINEARRING (... + 1 [] + dtype: object """ return _delegate_property("interiors", self) def representative_point(self): """Returns a ``GeoSeries`` of (cheaply computed) points that are guaranteed to be within each geometry. + + Examples + -------- + + >>> from shapely.geometry import Polygon, LineString, Point + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... LineString([(0, 0), (1, 1), (1, 0)]), + ... Point(0, 0), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 LINESTRING (0.00000 0.00000, 1.00000 1.00000, ... + 2 POINT (0.00000 0.00000) + dtype: geometry + + >>> s.representative_point() + 0 POINT (0.25000 0.50000) + 1 POINT (1.00000 1.00000) + 2 POINT (0.00000 0.00000) + dtype: geometry """ return _delegate_geo_method("representative_point", self) @@ -283,7 +641,22 @@ class GeoPandasBase(object): @property def unary_union(self): """Returns a geometry containing the union of all geometries in the - ``GeoSeries``.""" + ``GeoSeries``. + + Examples + -------- + + >>> from shapely.geometry import box + >>> s = geopandas.GeoSeries([box(0,0,1,1), box(0,0,2,2)]) + >>> s + 0 POLYGON ((1.00000 0.00000, 1.00000 1.00000, 0.... + 1 POLYGON ((2.00000 0.00000, 2.00000 2.00000, 0.... + dtype: geometry + + >>> union = s.unary_union + >>> print(union) + POLYGON ((0 0, 0 1, 0 2, 2 2, 2 0, 1 0, 0 0)) + """ return self.geometry.values.unary_union() # diff --git a/geopandas/geodataframe.py b/geopandas/geodataframe.py index 8b7d82e..357ec2a 100644 --- a/geopandas/geodataframe.py +++ b/geopandas/geodataframe.py @@ -205,8 +205,31 @@ class GeoDataFrame(GeoPandasBase, DataFrame): Examples -------- - >>> df1 = df.set_geometry([Point(0,0), Point(1,1), Point(2,2)]) - >>> df2 = df.set_geometry('geom1') + >>> from shapely.geometry import Point + >>> d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]} + >>> gdf = geopandas.GeoDataFrame(d, crs="EPSG:4326") + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 2.00000) + 1 name2 POINT (2.00000 1.00000) + + Passing an array: + + >>> df1 = gdf.set_geometry([Point(0,0), Point(1,1)]) + >>> df1 + col1 geometry + 0 name1 POINT (0.00000 0.00000) + 1 name2 POINT (1.00000 1.00000) + + Using existing column: + + >>> gdf["buffered"] = gdf.buffer(2) + >>> df2 = df.set_geometry("buffered") + >>> df2.geometry + 0 POLYGON ((3.00000 2.00000, 2.99037 1.80397, 2.... + 1 POLYGON ((4.00000 1.00000, 3.99037 0.80397, 3.... + Name: buffered, dtype: geometry + Returns ------- @@ -310,6 +333,23 @@ class GeoDataFrame(GeoPandasBase, DataFrame): can be anything accepted by :meth:`pyproj.CRS.from_user_input() `, such as an authority string (eg "EPSG:4326") or a WKT string. + + Examples + -------- + + >>> gdf.crs + + Name: WGS 84 + Axis Info [ellipsoidal]: + - Lat[north]: Geodetic latitude (degree) + - Lon[east]: Geodetic longitude (degree) + Area of Use: + - name: World + - bounds: (-180.0, -90.0, 180.0, 90.0) + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich + """ return self._crs @@ -358,6 +398,8 @@ class GeoDataFrame(GeoPandasBase, DataFrame): def from_file(cls, filename, **kwargs): """Alternate constructor to create a ``GeoDataFrame`` from a file. + It is recommended to use :func:`geopandas.read_file` instead. + Can load a ``GeoDataFrame`` from a file in any format recognized by `fiona`. See http://fiona.readthedocs.io/en/latest/manual.html for details. @@ -374,7 +416,31 @@ class GeoDataFrame(GeoPandasBase, DataFrame): Examples -------- - >>> df = geopandas.GeoDataFrame.from_file('nybb.shp') + + >>> path = geopandas.datasets.get_path('nybb') + >>> gdf = geopandas.GeoDataFrame.from_file(path) + >>> gdf + BoroCode BoroName Shape_Leng Shape_Area \ + geometry + 0 5 Staten Island 330470.010332 1.623820e+09 MULTIPOLYGON ((\ +(970217.022 145643.332, 970227.... + 1 4 Queens 896344.047763 3.045213e+09 MULTIPOLYGON ((\ +(1029606.077 156073.814, 102957... + 2 3 Brooklyn 741080.523166 1.937479e+09 MULTIPOLYGON ((\ +(1021176.479 151374.797, 102100... + 3 1 Manhattan 359299.096471 6.364715e+08 MULTIPOLYGON ((\ +(981219.056 188655.316, 980940.... + 4 2 Bronx 464392.991824 1.186925e+09 MULTIPOLYGON ((\ +(1012821.806 229228.265, 101278... + + The recommended method of reading files is :func:`geopandas.read_file`: + + >>> gdf = geopandas.read_file(path) + + See also + -------- + read_file + """ return geopandas.io.file._read_file(filename, **kwargs) @@ -409,6 +475,34 @@ class GeoDataFrame(GeoPandasBase, DataFrame): For more information about the ``__geo_interface__``, see https://gist.github.com/sgillies/2217756 + Examples + -------- + >>> feature_coll = { + ... "type": "FeatureCollection", + ... "features": [ + ... { + ... "id": "0", + ... "type": "Feature", + ... "properties": {"col1": "name1"}, + ... "geometry": {"type": "Point", "coordinates": (1.0, 2.0)}, + ... "bbox": (1.0, 2.0, 1.0, 2.0), + ... }, + ... { + ... "id": "1", + ... "type": "Feature", + ... "properties": {"col1": "name2"}, + ... "geometry": {"type": "Point", "coordinates": (2.0, 1.0)}, + ... "bbox": (2.0, 1.0, 2.0, 1.0), + ... }, + ... ], + ... "bbox": (1.0, 1.0, 2.0, 2.0), + ... } + >>> df = geopandas.GeoDataFrame.from_features(feature_coll) + >>> df + geometry col1 + 0 POINT (1.00000 2.00000) name1 + 1 POINT (2.00000 1.00000) name2 + """ # Handle feature collections if hasattr(features, "__geo_interface__"): @@ -523,6 +617,24 @@ class GeoDataFrame(GeoPandasBase, DataFrame): - ``drop``: remove the property from the feature. This applies to each feature individually so that features may have different properties. - ``keep``: output the missing entries as NaN. + + Examples + -------- + + >>> from shapely.geometry import Point + >>> d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]} + >>> gdf = geopandas.GeoDataFrame(d, crs="EPSG:4326") + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 2.00000) + 1 name2 POINT (2.00000 1.00000) + + >>> gdf.to_json() + '{"type": "FeatureCollection", "features": [{"id": "0", "type": "Feature", \ +"properties": {"col1": "name1"}, "geometry": {"type": "Point", "coordinates": [1.0,\ + 2.0]}}, {"id": "1", "type": "Feature", "properties": {"col1": "name2"}, "geometry"\ +: {"type": "Point", "coordinates": [2.0, 1.0]}}]}' + """ return json.dumps(self._to_geo(na=na, show_bbox=show_bbox), **kwargs) @@ -536,6 +648,26 @@ class GeoDataFrame(GeoPandasBase, DataFrame): This differs from `_to_geo()` only in that it is a property with default args instead of a method + + Examples + -------- + + >>> from shapely.geometry import Point + >>> d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]} + >>> gdf = geopandas.GeoDataFrame(d, crs="EPSG:4326") + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 2.00000) + 1 name2 POINT (2.00000 1.00000) + + >>> gdf.__geo_interface__ + {'type': 'FeatureCollection', 'features': [{'id': '0', 'type': 'Feature', \ +'properties': {'col1': 'name1'}, 'geometry': {'type': 'Point', 'coordinates': (1.0\ +, 2.0)}, 'bbox': (1.0, 2.0, 1.0, 2.0)}, {'id': '1', 'type': 'Feature', 'properties\ +': {'col1': 'name2'}, 'geometry': {'type': 'Point', 'coordinates': (2.0, 1.0)}, 'b\ +box': (2.0, 1.0, 2.0, 1.0)}], 'bbox': (1.0, 1.0, 2.0, 2.0)} + + """ return self._to_geo(na="null", show_bbox=True) @@ -555,6 +687,22 @@ class GeoDataFrame(GeoPandasBase, DataFrame): * keep: output the missing entries as NaN show_bbox : include bbox (bounds) in the geojson. default False + + Examples + -------- + + >>> from shapely.geometry import Point + >>> d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]} + >>> gdf = geopandas.GeoDataFrame(d, crs="EPSG:4326") + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 2.00000) + 1 name2 POINT (2.00000 1.00000) + + >>> feature = next(gdf.iterfeatures()) + >>> feature + {'id': '0', 'type': 'Feature', 'properties': {'col1': 'name1'}, 'geometry': {\ +'type': 'Point', 'coordinates': (1.0, 2.0)}} """ if na not in ["null", "drop", "keep"]: raise ValueError("Unknown na method {0}".format(na)) @@ -656,6 +804,11 @@ class GeoDataFrame(GeoPandasBase, DataFrame): Name of the compression to use. Use ``None`` for no compression. kwargs Additional keyword arguments passed to to pyarrow.parquet.write_table(). + + Examples + -------- + + >>> gdf.to_parquet('data.parquet') """ from geopandas.io.arrow import _to_parquet @@ -694,6 +847,11 @@ class GeoDataFrame(GeoPandasBase, DataFrame): compression. By default uses LZ4 if available, otherwise uncompressed. kwargs Additional keyword arguments passed to to pyarrow.feather.write_feather(). + + Examples + -------- + + >>> gdf.to_feather('data.feather') """ from geopandas.io.arrow import _to_feather @@ -743,6 +901,15 @@ class GeoDataFrame(GeoPandasBase, DataFrame): See Also -------- GeoSeries.to_file + + Examples + -------- + + >>> gdf.to_file('dataframe.shp') + + >>> gdf.to_file('dataframe.gpkg', driver='GPKG', layer='name1') + + >>> gdf.to_file('dataframe.geojson', driver='GeoJSON') """ from geopandas.io.file import _to_file @@ -773,6 +940,45 @@ class GeoDataFrame(GeoPandasBase, DataFrame): allow_override : bool, default False If the the GeoDataFrame already has a CRS, allow to replace the existing CRS, even when both are not equal. + + Examples + -------- + >>> from shapely.geometry import Point + >>> d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]} + >>> gdf = geopandas.GeoDataFrame(d) + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 2.00000) + 1 name2 POINT (2.00000 1.00000) + + Setting CRS to a GeoDataFrame without one: + + >>> gdf.crs is None + True + + >>> gdf = gdf.set_crs('epsg:3857') + >>> gdf.crs + + Name: WGS 84 / Pseudo-Mercator + Axis Info [cartesian]: + - X[east]: Easting (metre) + - Y[north]: Northing (metre) + Area of Use: + - name: World - 85°S to 85°N + - bounds: (-180.0, -85.06, 180.0, 85.06) + Coordinate Operation: + - name: Popular Visualisation Pseudo-Mercator + - method: Popular Visualisation Pseudo Mercator + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich + + Overriding existing CRS: + + >>> gdf = gdf.set_crs(4326, allow_override=True) + + Without ``allow_override=True``, ``set_crs`` returns an error if you try to + override CRS. """ if not inplace: df = self.copy() @@ -811,6 +1017,49 @@ class GeoDataFrame(GeoPandasBase, DataFrame): Returns ------- GeoDataFrame + + Examples + -------- + >>> from shapely.geometry import Point + >>> d = {'col1': ['name1', 'name2'], 'geometry': [Point(1, 2), Point(2, 1)]} + >>> gdf = geopandas.GeoDataFrame(d, crs=4326) + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 1.00000) + 1 name2 POINT (2.00000 2.00000) + >>> gdf.crs + + Name: WGS 84 + Axis Info [ellipsoidal]: + - Lat[north]: Geodetic latitude (degree) + - Lon[east]: Geodetic longitude (degree) + Area of Use: + - name: World + - bounds: (-180.0, -90.0, 180.0, 90.0) + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich + + >>> gdf = gdf.to_crs(3857) + >>> gdf + col1 geometry + 0 name1 POINT (111319.491 222684.209) + 1 name2 POINT (222638.982 111325.143) + >>> gdf.crs + + Name: WGS 84 / Pseudo-Mercator + Axis Info [cartesian]: + - X[east]: Easting (metre) + - Y[north]: Northing (metre) + Area of Use: + - name: World - 85°S to 85°N + - bounds: (-180.0, -85.06, 180.0, 85.06) + Coordinate Operation: + - name: Popular Visualisation Pseudo-Mercator + - method: Popular Visualisation Pseudo Mercator + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich """ if inplace: df = self @@ -944,6 +1193,28 @@ class GeoDataFrame(GeoPandasBase, DataFrame): Returns ------- GeoDataFrame + + Examples + -------- + >>> from shapely.geometry import Point + >>> d = { + ... "col1": ["name1", "name2", "name1"], + ... "geometry": [Point(1, 2), Point(2, 1), Point(0, 1)], + ... } + >>> gdf = geopandas.GeoDataFrame(d, crs=4326) + >>> gdf + col1 geometry + 0 name1 POINT (1.00000 2.00000) + 1 name2 POINT (2.00000 1.00000) + 2 name1 POINT (0.00000 1.00000) + + >>> dissolved = gdf.dissolve('col1') + >>> dissolved + geometry + col1 + name1 MULTIPOINT (0.00000 1.00000, 1.00000 2.00000) + name2 POINT (2.00000 1.00000) + """ # Process non-spatial component @@ -990,6 +1261,30 @@ class GeoDataFrame(GeoPandasBase, DataFrame): Exploded geodataframe with each single geometry as a separate entry in the geodataframe. + Examples + -------- + + >>> from shapely.geometry import MultiPoint + >>> d = { + ... "col1": ["name1", "name2"], + ... "geometry": [ + ... MultiPoint([(1, 2), (3, 4)]), + ... MultiPoint([(2, 1), (0, 0)]), + ... ], + ... } + >>> gdf = geopandas.GeoDataFrame(d, crs=4326) + >>> gdf + col1 geometry + 0 name1 MULTIPOINT (1.00000 2.00000, 3.00000 4.00000) + 1 name2 MULTIPOINT (2.00000 1.00000, 0.00000 0.00000) + + >>> exploded = gdf.explode() + >>> exploded + col1 geometry + 0 0 name1 POINT (1.00000 2.00000) + 1 name1 POINT (3.00000 4.00000) + 1 0 name2 POINT (2.00000 1.00000) + 1 name2 POINT (0.00000 0.00000) """ df_copy = self.copy() diff --git a/geopandas/geoseries.py b/geopandas/geoseries.py index b79f598..078f4f8 100644 --- a/geopandas/geoseries.py +++ b/geopandas/geoseries.py @@ -193,12 +193,56 @@ class GeoSeries(GeoPandasBase, Series): @property def x(self): - """Return the x location of point geometries in a GeoSeries""" + """Return the x location of point geometries in a GeoSeries + + Returns + ------- + pandas.Series + + Examples + -------- + + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)]) + >>> s.x + 0 1.0 + 1 2.0 + 2 3.0 + dtype: float64 + + See Also + -------- + + GeoSeries.y + + """ return _delegate_property("x", self) @property def y(self): - """Return the y location of point geometries in a GeoSeries""" + """Return the y location of point geometries in a GeoSeries + + Returns + ------- + pandas.Series + + Examples + -------- + + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)]) + >>> s.y + 0 1.0 + 1 2.0 + 2 3.0 + dtype: float64 + + See Also + -------- + + GeoSeries.x + + """ return _delegate_property("y", self) @classmethod @@ -207,6 +251,8 @@ class GeoSeries(GeoPandasBase, Series): Can load a ``GeoSeries`` from a file from any format recognized by `fiona`. See http://fiona.readthedocs.io/en/latest/manual.html for details. + From a file with attributes loads only geometry column. Note that to do + that, GeoPandas first loads the whole GeoDataFrame. Parameters ---------- @@ -218,6 +264,19 @@ class GeoSeries(GeoPandasBase, Series): These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc. + + Examples + -------- + + >>> path = geopandas.datasets.get_path('nybb') + >>> s = geopandas.GeoSeries.from_file(path) + >>> s + 0 MULTIPOLYGON (((970217.022 145643.332, 970227.... + 1 MULTIPOLYGON (((1029606.077 156073.814, 102957... + 2 MULTIPOLYGON (((1021176.479 151374.797, 102100... + 3 MULTIPOLYGON (((981219.056 188655.316, 980940.... + 4 MULTIPOLYGON (((1012821.806 229228.265, 101278... + Name: geometry, dtype: geometry """ from geopandas import GeoDataFrame @@ -233,6 +292,20 @@ class GeoSeries(GeoPandasBase, Series): represents the ``GeoSeries`` as a GeoJSON-like ``FeatureCollection``. Note that the features will have an empty ``properties`` dict as they don't have associated attributes (geometry only). + + Examples + -------- + + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)]) + >>> s.__geo_interface__ + {'type': 'FeatureCollection', 'features': [{'id': '0', 'type': 'Feature', \ +'properties': {}, 'geometry': {'type': 'Point', 'coordinates': (1.0, 1.0)}, \ +'bbox': (1.0, 1.0, 1.0, 1.0)}, {'id': '1', 'type': 'Feature', \ +'properties': {}, 'geometry': {'type': 'Point', 'coordinates': (2.0, 2.0)}, \ +'bbox': (2.0, 2.0, 2.0, 2.0)}, {'id': '2', 'type': '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)} """ from geopandas import GeoDataFrame @@ -268,6 +341,15 @@ class GeoSeries(GeoPandasBase, Series): See Also -------- GeoDataFrame.to_file + + Examples + -------- + + >>> s.to_file('series.shp') + + >>> s.to_file('series.gpkg', driver='GPKG', layer='name1') + + >>> s.to_file('series.geojson', driver='GeoJSON') """ from geopandas import GeoDataFrame @@ -342,6 +424,24 @@ class GeoSeries(GeoPandasBase, Series): A boolean pandas Series of the same size as the GeoSeries, True where a value is NA. + Examples + -------- + + >>> from shapely.geometry import Polygon + >>> s = geopandas.GeoSeries( + ... [Polygon([(0, 0), (1, 1), (0, 1)]), None, Polygon([])] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 None + 2 GEOMETRYCOLLECTION EMPTY + dtype: geometry + >>> s.isna() + 0 False + 1 True + 2 False + dtype: bool + See Also -------- GeoSeries.notna : inverse of isna @@ -383,6 +483,24 @@ class GeoSeries(GeoPandasBase, Series): A boolean pandas Series of the same size as the GeoSeries, False where a value is NA. + Examples + -------- + + >>> from shapely.geometry import Polygon + >>> s = geopandas.GeoSeries( + ... [Polygon([(0, 0), (1, 1), (0, 1)]), None, Polygon([])] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 None + 2 GEOMETRYCOLLECTION EMPTY + dtype: geometry + >>> s.notna() + 0 True + 1 False + 2 True + dtype: bool + See Also -------- GeoSeries.isna : inverse of notna @@ -412,6 +530,35 @@ class GeoSeries(GeoPandasBase, Series): """Fill NA values with a geometry (empty polygon by default). "method" is currently not implemented for pandas <= 0.12. + + Examples + -------- + + >>> from shapely.geometry import Polygon + >>> s = geopandas.GeoSeries( + ... [ + ... Polygon([(0, 0), (1, 1), (0, 1)]), + ... None, + ... Polygon([(0, 0), (-1, 1), (0, -1)]), + ... ] + ... ) + >>> s + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 None + 2 POLYGON ((0.00000 0.00000, -1.00000 1.00000, 0... + dtype: geometry + + >>> s.fillna() + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 GEOMETRYCOLLECTION EMPTY + 2 POLYGON ((0.00000 0.00000, -1.00000 1.00000, 0... + dtype: geometry + + >>> s.fillna(Polygon([(0, 1), (2, 1), (1, 2)])) + 0 POLYGON ((0.00000 0.00000, 1.00000 1.00000, 0.... + 1 POLYGON ((0.00000 1.00000, 2.00000 1.00000, 1.... + 2 POLYGON ((0.00000 0.00000, -1.00000 1.00000, 0... + dtype: geometry """ if value is None: value = BaseGeometry() @@ -471,6 +618,45 @@ class GeoSeries(GeoPandasBase, Series): Returns ------- GeoSeries + + Examples + -------- + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)]) + >>> s + 0 POINT (1.00000 1.00000) + 1 POINT (2.00000 2.00000) + 2 POINT (3.00000 3.00000) + + Setting CRS to a GeoSeries without one: + + >>> s.crs is None + True + + >>> s = s.set_crs('epsg:3857') + >>> s.crs + + Name: WGS 84 / Pseudo-Mercator + Axis Info [cartesian]: + - X[east]: Easting (metre) + - Y[north]: Northing (metre) + Area of Use: + - name: World - 85°S to 85°N + - bounds: (-180.0, -85.06, 180.0, 85.06) + Coordinate Operation: + - name: Popular Visualisation Pseudo-Mercator + - method: Popular Visualisation Pseudo Mercator + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich + + Overriding existing CRS: + + >>> s = s.set_crs(4326, allow_override=True) + + Without ``allow_override=True``, ``set_crs`` returns an error if you try to + override CRS. + """ if crs is not None: crs = CRS.from_user_input(crs) @@ -519,6 +705,49 @@ class GeoSeries(GeoPandasBase, Series): Returns ------- GeoSeries + + Examples + -------- + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)], crs=4326) + >>> s + 0 POINT (1.00000 1.00000) + 1 POINT (2.00000 2.00000) + 2 POINT (3.00000 3.00000) + >>> s.crs + + Name: WGS 84 + Axis Info [ellipsoidal]: + - Lat[north]: Geodetic latitude (degree) + - Lon[east]: Geodetic longitude (degree) + Area of Use: + - name: World + - bounds: (-180.0, -90.0, 180.0, 90.0) + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich + + >>> s = s.to_crs(3857) + >>> s + 0 POINT (111319.491 111325.143) + 1 POINT (222638.982 222684.209) + 2 POINT (333958.472 334111.171) + >>> s.crs + + Name: WGS 84 / Pseudo-Mercator + Axis Info [cartesian]: + - X[east]: Easting (metre) + - Y[north]: Northing (metre) + Area of Use: + - name: World - 85°S to 85°N + - bounds: (-180.0, -85.06, 180.0, 85.06) + Coordinate Operation: + - name: Popular Visualisation Pseudo-Mercator + - method: Popular Visualisation Pseudo Mercator + Datum: World Geodetic System 1984 + - Ellipsoid: WGS 84 + - Prime Meridian: Greenwich + """ if self.crs is None: raise ValueError( @@ -550,6 +779,27 @@ class GeoSeries(GeoPandasBase, Series): Parameters ---------- *kwargs* that will be passed to json.dumps(). + + Returns + ------- + JSON string + + Examples + -------- + >>> from shapely.geometry import Point + >>> s = geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)]) + >>> s + 0 POINT (1.00000 1.00000) + 1 POINT (2.00000 2.00000) + 2 POINT (3.00000 3.00000) + + >>> s.to_json() + '{"type": "FeatureCollection", "features": [{"id": "0", "type": "Feature", "pr\ +operties": {}, "geometry": {"type": "Point", "coordinates": [1.0, 1.0]}, "bbox": [1.0,\ + 1.0, 1.0, 1.0]}, {"id": "1", "type": "Feature", "properties": {}, "geometry": {"type"\ +: "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]}' """ return json.dumps(self.__geo_interface__, **kwargs)