Reference¶
GeoSeries¶
The following Shapely methods and attributes are available on
GeoSeries
objects:
-
GeoSeries.
area
¶ Returns a
Series
containing the area of each geometry in theGeoSeries
.
-
GeoSeries.
bounds
¶ Returns a
DataFrame
with columnsminx
,miny
,maxx
,maxy
values containing the bounds for each geometry.See
GeoSeries.total_bounds
for the limits of the entire series.
-
GeoSeries.
length
¶ Returns a
Series
containing the length of each geometry.
-
GeoSeries.
geom_type
¶ Returns a
Series
of strings specifying the Geometry Type of each object.
-
GeoSeries.
distance
(self, other)¶ Returns a
Series
containing the distance to other.- Parameters
- otherGeoseries or geometric object
The Geoseries (elementwise) or geometric object to find the distance to.
-
GeoSeries.
representative_point
(self)¶ Returns a
GeoSeries
of (cheaply computed) points that are guaranteed to be within each geometry.
-
GeoSeries.
exterior
¶ Returns a
GeoSeries
of LinearRings representing the outer boundary of each polygon in the GeoSeries.Applies to GeoSeries containing only Polygons.
-
GeoSeries.
interiors
¶ Returns a
Series
of List representing the inner rings of each polygon in the GeoSeries.Applies to GeoSeries containing only Polygons.
- Returns
- inner_rings: Series of List
Inner rings of each polygon in the GeoSeries.
-
GeoSeries.
x
¶ Return the x location of point geometries in a GeoSeries
-
GeoSeries.
y
¶ Return the y location of point geometries in a GeoSeries
Unary Predicates
-
GeoSeries.
is_empty
¶ Returns a
Series
ofdtype('bool')
with valueTrue
for empty geometries.See also
GeoSeries.isna
detect missing values
Examples
An example of a GeoDataFrame with one empty point, one point and one missing value:
>>> from shapely.geometry import Point >>> d = {'geometry': [Point(), Point(2,1), None]} >>> gdf = gpd.GeoDataFrame(d, crs="EPSG:4326") >>> gdf geometry 0 GEOMETRYCOLLECTION EMPTY 1 POINT (2.00000 1.00000) 2 None >>> gdf.is_empty 0 True 1 False 2 False dtype: bool
-
GeoSeries.
is_ring
¶ Returns a
Series
ofdtype('bool')
with valueTrue
for features that are closed.
-
GeoSeries.
is_simple
¶ Returns a
Series
ofdtype('bool')
with valueTrue
for geometries that do not cross themselves.This is meaningful only for LineStrings and LinearRings.
-
GeoSeries.
is_valid
¶ Returns a
Series
ofdtype('bool')
with valueTrue
for geometries that are valid.
Binary Predicates
-
GeoSeries.
geom_almost_equals
(self, other, decimal=6)¶ Returns a
Series
ofdtype('bool')
with valueTrue
if each geometry is approximately equal to other.Approximate equality is tested at all points to the specified decimal place precision. See also
geom_equals()
.- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to compare to.
- decimalint
Decimal place presion used when testing for approximate equality.
-
GeoSeries.
contains
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry that contains other.An object is said to contain other if its interior contains the boundary and interior of the other object and their boundaries do not touch at all.
This is the inverse of
within()
in the sense that the expressiona.contains(b) == b.within(a)
always evaluates toTrue
.- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if is contained.
-
GeoSeries.
crosses
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry that cross other.An object is said to cross other if its interior intersects the interior of the other but does not contain it, and the dimension of the intersection is less than the dimension of the one or the other.
- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if is crossed.
-
GeoSeries.
disjoint
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry disjoint to other.An object is said to be disjoint to other if its boundary and interior does not intersect at all with those of the other.
- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if is disjoint.
-
GeoSeries.
geom_equals
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry equal to other.An object is said to be equal to other if its set-theoretic boundary, interior, and exterior coincides with those of the other.
- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test for equality.
-
GeoSeries.
intersects
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry that intersects other.An object is said to intersect other if its boundary and interior intersects in any way with those of the other.
- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if is intersected.
-
GeoSeries.
overlaps
(self, other)¶ Returns True for all geometries that overlap other, else False.
- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if overlaps.
-
GeoSeries.
touches
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry that touches other.An object is said to touch other if it has at least one point in common with other and its interior does not intersect with any part of the other.
- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if is touched.
-
GeoSeries.
within
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry that is within other.An object is said to be within other if its boundary and interior intersects only with the interior of the other (not its boundary or exterior).
This is the inverse of
contains()
in the sense that the expressiona.within(b) == b.contains(a)
always evaluates toTrue
.- Parameters
- otherGeoSeries or geometric object
The GeoSeries (elementwise) or geometric object to test if each geometry is within.
-
GeoSeries.
covers
(self, other)¶ Returns a
Series
ofdtype('bool')
with valueTrue
for each geometry that is entirely covering other.An object A is said to cover another object B if no points of B lie in the exterior of A.
See https://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html for reference.
- Parameters
- otherGeoseries or geometric object
The Geoseries (elementwise) or geometric object to check is being covered.
Set-theoretic Methods
-
GeoSeries.
difference
(self, other)¶ Returns a
GeoSeries
of the points in each geometry that are not in other.- Parameters
- otherGeoseries or geometric object
The Geoseries (elementwise) or geometric object to find the difference to.
-
GeoSeries.
intersection
(self, other)¶ Returns a
GeoSeries
of the intersection of points in each geometry with other.- Parameters
- otherGeoseries or geometric object
The Geoseries (elementwise) or geometric object to find the intersection with.
-
GeoSeries.
symmetric_difference
(self, other)¶ Returns a
GeoSeries
of the symmetric difference of points in each geometry with other.For each geometry, the symmetric difference consists of points in the geometry not in other, and points in other not in the geometry.
- Parameters
- otherGeoseries or geometric object
The Geoseries (elementwise) or geometric object to find the symmetric difference to.
-
GeoSeries.
union
(self, other)¶ Returns a
GeoSeries
of the union of points in each geometry with other.- Parameters
- otherGeoseries or geometric object
The Geoseries (elementwise) or geometric object to find the union with.
Constructive Methods
-
GeoSeries.
buffer
(self, distance, resolution=16, \*\*kwargs)¶ Returns a
GeoSeries
of geometries representing all points within a given distance of each geometric object.See http://shapely.readthedocs.io/en/latest/manual.html#object.buffer for details.
- Parameters
- distancefloat, np.array, pd.Series
The radius of the buffer. If np.array or pd.Series are used then it must have same length as the GeoSeries.
- resolution: int
Optional, the resolution of the buffer around each vertex.
-
GeoSeries.
boundary
¶ Returns a
GeoSeries
of lower dimensional objects representing each geometries’s set-theoretic boundary.
-
GeoSeries.
centroid
¶ Returns a
GeoSeries
of points representing the centroid of each geometry.
-
GeoSeries.
convex_hull
¶ Returns a
GeoSeries
of geometries representing the convex hull of each geometry.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.
-
GeoSeries.
envelope
¶ Returns a
GeoSeries
of geometries representing the envelope of each geometry.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.
-
GeoSeries.
simplify
(self, \*args, \*\*kwargs)¶ Returns a
GeoSeries
containing a simplified representation of each geometry.See http://shapely.readthedocs.io/en/latest/manual.html#object.simplify for details
- Parameters
- tolerancefloat
All points in a simplified geometry will be no more than tolerance distance from the original.
- preserve_topology: bool
False uses a quicker algorithm, but may produce self-intersecting or otherwise invalid geometries.
Affine transformations
-
GeoSeries.
affine_transform
(self, matrix)¶ Return a
GeoSeries
with translated geometries.See http://shapely.readthedocs.io/en/stable/manual.html#shapely.affinity.affine_transform for details.
- Parameters
- matrix: List or tuple
6 or 12 items for 2D or 3D transformations respectively. For 2D affine transformations, the 6 parameter matrix is [a, b, d, e, xoff, yoff] For 3D affine transformations, the 12 parameter matrix is [a, b, c, d, e, f, g, h, i, xoff, yoff, zoff]
-
GeoSeries.
rotate
(self, angle, origin='center', use_radians=False)¶ Returns a
GeoSeries
with rotated geometries.See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.rotate for details.
- Parameters
- anglefloat
The angle of rotation can be specified in either degrees (default) or radians by setting use_radians=True. Positive angles are counter-clockwise and negative are clockwise rotations.
- originstring, Point, or tuple (x, y)
The point of origin can be a keyword ‘center’ for the bounding box center (default), ‘centroid’ for the geometry’s centroid, a Point object or a coordinate tuple (x, y).
- use_radiansboolean
Whether to interpret the angle of rotation as degrees or radians
-
GeoSeries.
scale
(self, xfact=1.0, yfact=1.0, zfact=1.0, origin='center')¶ Returns a
GeoSeries
with scaled geometries.The geometries can be scaled by different factors along each dimension. Negative scale factors will mirror or reflect coordinates.
See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.scale for details.
- Parameters
- xfact, yfact, zfactfloat, float, float
Scaling factors for the x, y, and z dimensions respectively.
- originstring, Point, or tuple
The point of origin can be a keyword ‘center’ for the 2D bounding box center (default), ‘centroid’ for the geometry’s 2D centroid, a Point object or a coordinate tuple (x, y, z).
-
GeoSeries.
skew
(self, xs=0.0, ys=0.0, origin='center', use_radians=False)¶ Returns a
GeoSeries
with skewed geometries.The geometries are sheared by angles along the x and y dimensions.
See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.skew for details.
- Parameters
- xs, ysfloat, float
The shear angle(s) for the x and y axes respectively. These can be specified in either degrees (default) or radians by setting use_radians=True.
- originstring, Point, or tuple (x, y)
The point of origin can be a keyword ‘center’ for the bounding box center (default), ‘centroid’ for the geometry’s centroid, a Point object or a coordinate tuple (x, y).
- use_radiansboolean
Whether to interpret the shear angle(s) as degrees or radians
-
GeoSeries.
translate
(self, xoff=0.0, yoff=0.0, zoff=0.0)¶ Returns a
GeoSeries
with translated geometries.See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.translate for details.
- Parameters
- xoff, yoff, zofffloat, float, float
Amount of offset along each dimension. xoff, yoff, and zoff for translation along the x, y, and z dimensions respectively.
Aggregating methods
-
GeoSeries.
unary_union
¶ Returns a geometry containing the union of all geometries in the
GeoSeries
.
Additionally, the following attributes and methods are implemented:
-
classmethod
GeoSeries.
from_file
(filename, \*\*kwargs)¶ Alternate constructor to create a
GeoSeries
from a file.Can load a
GeoSeries
from a file from any format recognized by fiona. See http://fiona.readthedocs.io/en/latest/manual.html for details.- Parameters
- filenamestr
File path or file handle to read from. Depending on which kwargs are included, the content of filename may vary. See http://fiona.readthedocs.io/en/latest/README.html#usage for usage details.
- kwargskey-word arguments
These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc.
-
GeoSeries.
to_file
(self, filename, driver='ESRI Shapefile', index=None, \*\*kwargs)¶ Write the
GeoSeries
to a file.By default, an ESRI shapefile is written, but any OGR data source supported by Fiona can be written.
- Parameters
- filenamestring
File path or file handle to write to.
- driverstring, default: ‘ESRI Shapefile’
The OGR format driver used to write the vector file.
- indexbool, default None
If True, write index into one or more columns (for MultiIndex). Default None writes the index into one or more columns only if the index is named, is a MultiIndex, or has a non-integer data type. If False, no index is written.
New in version 0.7: Previously the index was not written.
See also
Notes
The extra keyword arguments
**kwargs
are passed to fiona.open and can be used to write to multi-layer data, store data within archives (zip files), etc.
-
GeoSeries.
to_json
(self, \*\*kwargs)¶ Returns a GeoJSON string representation of the GeoSeries.
- Parameters
- *kwargs* that will be passed to json.dumps().
-
GeoSeries.
crs
¶ The Coordinate Reference System (CRS) represented as a
pyproj.CRS
object.Returns None if the CRS is not set, and to set the value it :getter: Returns a
pyproj.CRS
or None. When setting, the value can be anything accepted bypyproj.CRS.from_user_input()
, such as an authority string (eg “EPSG:4326”) or a WKT string.
-
GeoSeries.
to_crs
(self, crs=None, epsg=None)¶ Returns a
GeoSeries
with all geometries transformed to a new coordinate reference system.Transform all geometries in a GeoSeries to a different coordinate reference system. The
crs
attribute on the current GeoSeries must be set. Eithercrs
orepsg
may be specified for output.This method will transform all points in all objects. It has no notion or projecting entire geometries. All segments joining points are assumed to be lines in the current projection, not geodesics. Objects crossing the dateline (or other projection boundary) will have undesirable behavior.
- Parameters
- crspyproj.CRS, optional if epsg is specified
The value can be anything accepted by
pyproj.CRS.from_user_input()
, such as an authority string (eg “EPSG:4326”) or a WKT string.- epsgint, optional if crs is specified
EPSG code specifying output projection.
- Returns
- GeoSeries
-
GeoSeries.
plot
(self, \*args, \*\*kwargs)¶ Plot a GeoSeries.
Generate a plot of a GeoSeries geometry with matplotlib.
- Parameters
- sSeries
The GeoSeries to be plotted. Currently Polygon, MultiPolygon, LineString, MultiLineString and Point geometries can be plotted.
- cmapstr (default None)
The name of a colormap recognized by matplotlib. Any colormap will work, but categorical colormaps are generally recommended. Examples of useful discrete colormaps include:
tab10, tab20, Accent, Dark2, Paired, Pastel1, Set1, Set2
- colorstr (default None)
If specified, all objects will be colored uniformly.
- axmatplotlib.pyplot.Artist (default None)
axes on which to draw the plot
- figsizepair of floats (default None)
Size of the resulting matplotlib.figure.Figure. If the argument ax is given explicitly, figsize is ignored.
- aspect‘auto’, ‘equal’ or float (default ‘auto’)
Set aspect of axis. If ‘auto’, the default aspect for map plots is ‘equal’; if however data are not projected (coordinates are long/lat), the aspect is by default set to 1/cos(s_y * pi/180) with s_y the y coordinate of the middle of the GeoSeries (the mean of the y range of bounding box) so that a long/lat square appears square in the middle of the plot. This implies an Equirectangular projection. It can also be set manually (float) as the ratio of y-unit to x-unit.
- **style_kwdsdict
Color options to be passed on to the actual plot function, such as
edgecolor
,facecolor
,linewidth
,markersize
,alpha
.
- Returns
- axmatplotlib axes instance
-
GeoSeries.
total_bounds
¶ Returns a tuple containing
minx
,miny
,maxx
,maxy
values for the bounds of the series as a whole.See
GeoSeries.bounds
for the bounds of the geometries contained in the series.
-
GeoSeries.
__geo_interface__
¶ Returns a
GeoSeries
as a python feature collection.Implements the geo_interface. The returned python data structure represents the
GeoSeries
as a GeoJSON-likeFeatureCollection
. Note that the features will have an emptyproperties
dict as they don’t have associated attributes (geometry only).
-
GeoSeries.
isna
(self)¶ Detect missing values.
Historically, NA values in a GeoSeries could be represented by empty geometric objects, in addition to standard representations such as None and np.nan. This behaviour is changed in version 0.6.0, and now only actual missing values return True. To detect empty geometries, use
GeoSeries.is_empty
instead.- Returns
- A boolean pandas Series of the same size as the GeoSeries,
- True where a value is NA.
See also
GeoSeries.notna
inverse of isna
GeoSeries.is_empty
detect empty geometries
-
GeoSeries.
notna
(self)¶ Detect non-missing values.
Historically, NA values in a GeoSeries could be represented by empty geometric objects, in addition to standard representations such as None and np.nan. This behaviour is changed in version 0.6.0, and now only actual missing values return False. To detect empty geometries, use
~GeoSeries.is_empty
instead.- Returns
- A boolean pandas Series of the same size as the GeoSeries,
- False where a value is NA.
See also
GeoSeries.isna
inverse of notna
GeoSeries.is_empty
detect empty geometries
-
GeoSeries.
fillna
(self, value=None, method=None, inplace=False, \*\*kwargs)¶ Fill NA values with a geometry (empty polygon by default).
“method” is currently not implemented for pandas <= 0.12.
Methods of pandas Series
objects are also available, although not
all are applicable to geometric objects and some may return a
Series
rather than a GeoSeries
result. The methods
isna()
and fillna()
have been
implemented specifically for GeoSeries
and are expected to work
correctly.
GeoDataFrame¶
A GeoDataFrame
is a tabular data structure that contains a column
called geometry
which contains a GeoSeries`.
Currently, the following methods/attributes are implemented for a GeoDataFrame
:
-
GeoDataFrame.
crs
¶ The Coordinate Reference System (CRS) represented as a
pyproj.CRS
object.Returns None if the CRS is not set, and to set the value it :getter: Returns a
pyproj.CRS
or None. When setting, the value can be anything accepted bypyproj.CRS.from_user_input()
, such as an authority string (eg “EPSG:4326”) or a WKT string.
-
GeoDataFrame.
to_crs
(self, crs=None, epsg=None, inplace=False)¶ Transform geometries to a new coordinate reference system.
Transform all geometries in an active geometry column to a different coordinate reference system. The
crs
attribute on the current GeoSeries must be set. Eithercrs
orepsg
may be specified for output.This method will transform all points in all objects. It has no notion or projecting entire geometries. All segments joining points are assumed to be lines in the current projection, not geodesics. Objects crossing the dateline (or other projection boundary) will have undesirable behavior.
- Parameters
- crspyproj.CRS, optional if epsg is specified
The value can be anything accepted by
pyproj.CRS.from_user_input()
, such as an authority string (eg “EPSG:4326”) or a WKT string.- epsgint, optional if crs is specified
EPSG code specifying output projection.
- inplacebool, optional, default: False
Whether to return a new GeoDataFrame or do the transformation in place.
- Returns
- GeoDataFrame
-
classmethod
GeoDataFrame.
from_file
(filename, \*\*kwargs)¶ Alternate constructor to create a
GeoDataFrame
from a file.Can load a
GeoDataFrame
from a file in any format recognized by fiona. See http://fiona.readthedocs.io/en/latest/manual.html for details.- Parameters
- filenamestr
File path or file handle to read from. Depending on which kwargs are included, the content of filename may vary. See http://fiona.readthedocs.io/en/latest/README.html#usage for usage details.
- kwargskey-word arguments
These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc.
Examples
>>> df = geopandas.GeoDataFrame.from_file('nybb.shp')
-
classmethod
GeoDataFrame.
from_features
(features, crs=None, columns=None)¶ Alternate constructor to create GeoDataFrame from an iterable of features or a feature collection.
- Parameters
- features
Iterable of features, where each element must be a feature dictionary or implement the __geo_interface__.
Feature collection, where the ‘features’ key contains an iterable of features.
Object holding a feature collection that implements the
__geo_interface__
.
- crsstr or dict (optional)
Coordinate reference system to set on the resulting frame.
- columnslist of column names, optional
Optionally specify the column names to include in the output frame. This does not overwrite the property names of the input, but can ensure a consistent output format.
- Returns
- GeoDataFrame
Notes
For more information about the
__geo_interface__
, see https://gist.github.com/sgillies/2217756
-
classmethod
GeoDataFrame.
from_postgis
(sql, con, geom_col='geom', crs=None, index_col=None, coerce_float=True, parse_dates=None, params=None, chunksize=None)¶ Alternate constructor to create a
GeoDataFrame
from a sql query containing a geometry column in WKB representation.- Parameters
- sqlstring
- conDB connection object or SQLAlchemy engine
- geom_colstring, default ‘geom’
column name to convert to shapely geometries
- crsoptional
Coordinate reference system to use for the returned GeoDataFrame
- index_colstring or list of strings, optional, default: None
Column(s) to set as index(MultiIndex)
- coerce_floatboolean, default True
Attempt to convert values of non-string, non-numeric objects (like decimal.Decimal) to floating point, useful for SQL result sets
- parse_dateslist or dict, default None
List of column names to parse as dates.
Dict of
{column_name: format string}
where format string is strftime compatible in case of parsing string times, or is one of (D, s, ns, ms, us) in case of parsing integer timestamps.Dict of
{column_name: arg dict}
, where the arg dict corresponds to the keyword arguments ofpandas.to_datetime()
. Especially useful with databases without native Datetime support, such as SQLite.
- paramslist, tuple or dict, optional, default None
List of parameters to pass to execute method.
- chunksizeint, default None
If specified, return an iterator where chunksize is the number of rows to include in each chunk.
Examples
>>> sql = "SELECT geom, highway FROM roads" SpatiaLite >>> sql = "SELECT ST_Binary(geom) AS geom, highway FROM roads" >>> df = geopandas.GeoDataFrame.from_postgis(sql, con)
-
GeoDataFrame.
to_crs
(self, crs=None, epsg=None, inplace=False)¶ Transform geometries to a new coordinate reference system.
Transform all geometries in an active geometry column to a different coordinate reference system. The
crs
attribute on the current GeoSeries must be set. Eithercrs
orepsg
may be specified for output.This method will transform all points in all objects. It has no notion or projecting entire geometries. All segments joining points are assumed to be lines in the current projection, not geodesics. Objects crossing the dateline (or other projection boundary) will have undesirable behavior.
- Parameters
- crspyproj.CRS, optional if epsg is specified
The value can be anything accepted by
pyproj.CRS.from_user_input()
, such as an authority string (eg “EPSG:4326”) or a WKT string.- epsgint, optional if crs is specified
EPSG code specifying output projection.
- inplacebool, optional, default: False
Whether to return a new GeoDataFrame or do the transformation in place.
- Returns
- GeoDataFrame
-
GeoDataFrame.
to_file
(self, filename, driver='ESRI Shapefile', schema=None, index=None, \*\*kwargs)¶ Write the
GeoDataFrame
to a file.By default, an ESRI shapefile is written, but any OGR data source supported by Fiona can be written. A dictionary of supported OGR providers is available via:
>>> import fiona >>> fiona.supported_drivers
- Parameters
- filenamestring
File path or file handle to write to.
- driverstring, default: ‘ESRI Shapefile’
The OGR format driver used to write the vector file.
- schemadict, default: None
If specified, the schema dictionary is passed to Fiona to better control how the file is written.
- indexbool, default None
If True, write index into one or more columns (for MultiIndex). Default None writes the index into one or more columns only if the index is named, is a MultiIndex, or has a non-integer data type. If False, no index is written.
New in version 0.7: Previously the index was not written.
See also
Notes
The extra keyword arguments
**kwargs
are passed to fiona.open and can be used to write to multi-layer data, store data within archives (zip files), etc.The format drivers will attempt to detect the encoding of your data, but may fail. In this case, the proper encoding can be specified explicitly by using the encoding keyword parameter, e.g.
encoding='utf-8'
.
-
GeoDataFrame.
to_json
(self, na='null', show_bbox=False, \*\*kwargs)¶ Returns a GeoJSON representation of the
GeoDataFrame
as a string.- Parameters
- na{‘null’, ‘drop’, ‘keep’}, default ‘null’
Indicates how to output missing (NaN) values in the GeoDataFrame. See below.
- show_bboxbool, optional, default: False
Include bbox (bounds) in the geojson
Notes
The remaining kwargs are passed to json.dumps().
Missing (NaN) values in the GeoDataFrame can be represented as follows:
null
: output the missing entries as JSON null.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.
-
GeoDataFrame.
to_parquet
(self, path, index=None, compression='snappy', \*\*kwargs)¶ Write a GeoDataFrame to the Parquet format.
Any geometry columns present are serialized to WKB format in the file.
Requires ‘pyarrow’.
WARNING: this is an initial implementation of Parquet file support and associated metadata. This is tracking version 0.1.0 of the metadata specification at: https://github.com/geopandas/geo-arrow-spec
This metadata specification does not yet make stability promises. As such, we do not yet recommend using this in a production setting unless you are able to rewrite your Parquet files.
New in version 0.8.
- Parameters
- pathstr, path object
- indexbool, default None
If
True
, always include the dataframe’s index(es) as columns in the file output. IfFalse
, the index(es) will not be written to the file. IfNone
, the index(ex) will be included as columns in the file output except RangeIndex which is stored as metadata only.- compression{‘snappy’, ‘gzip’, ‘brotli’, None}, default ‘snappy’
Name of the compression to use. Use
None
for no compression.- kwargs
Additional keyword arguments passed to to pyarrow.parquet.write_table().
-
GeoDataFrame.
to_feather
(self, path, index=None, compression=None, \*\*kwargs)¶ Write a GeoDataFrame to the Feather format.
Any geometry columns present are serialized to WKB format in the file.
Requires ‘pyarrow’ >= 0.17.
WARNING: this is an initial implementation of Feather file support and associated metadata. This is tracking version 0.1.0 of the metadata specification at: https://github.com/geopandas/geo-arrow-spec
This metadata specification does not yet make stability promises. As such, we do not yet recommend using this in a production setting unless you are able to rewrite your Feather files.
New in version 0.8.
- Parameters
- pathstr, path object
- indexbool, default None
If
True
, always include the dataframe’s index(es) as columns in the file output. IfFalse
, the index(es) will not be written to the file. IfNone
, the index(ex) will be included as columns in the file output except RangeIndex which is stored as metadata only.- compression{‘zstd’, ‘lz4’, ‘uncompressed’}, optional
Name of the compression to use. Use
"uncompressed"
for no compression. By default uses LZ4 if available, otherwise uncompressed.- kwargs
Additional keyword arguments passed to to pyarrow.feather.write_feather().
-
GeoDataFrame.
to_postgis
(self, name, con, schema=None, if_exists='fail', index=False, index_label=None, chunksize=None, dtype=None)¶ Upload GeoDataFrame into PostGIS database.
This method requires SQLAlchemy and GeoAlchemy2, and a PostgreSQL Python driver (e.g. psycopg2) to be installed.
- Parameters
- namestr
Name of the target table.
- consqlalchemy.engine.Engine
Active connection to the PostGIS database.
- if_exists{‘fail’, ‘replace’, ‘append’}, default ‘fail’
How to behave if the table already exists:
fail: Raise a ValueError.
replace: Drop the table before inserting new values.
append: Insert new values to the existing table.
- schemastring, optional
Specify the schema. If None, use default schema: ‘public’.
- indexbool, default True
Write DataFrame index as a column. Uses index_label as the column name in the table.
- index_labelstring or sequence, default None
Column label for index column(s). If None is given (default) and index is True, then the index names are used.
- chunksizeint, optional
Rows will be written in batches of this size at a time. By default, all rows will be written at once.
- dtypedict of column name to SQL type, default None
Specifying the datatype for columns. The keys should be the column names and the values should be the SQLAlchemy types.
Examples
>>> from sqlalchemy import create_engine >>> engine = create_engine("postgres://myusername:mypassword@myhost:5432/mydatabase";) >>> gdf.to_postgis("my_table", engine)
-
GeoDataFrame.
plot
(self, \*args, \*\*kwargs)¶ Plot a GeoDataFrame.
Generate a plot of a GeoDataFrame with matplotlib. If a column is specified, the plot coloring will be based on values in that column.
- Parameters
- dfGeoDataFrame
The GeoDataFrame to be plotted. Currently Polygon, MultiPolygon, LineString, MultiLineString and Point geometries can be plotted.
- columnstr, np.array, pd.Series (default None)
The name of the dataframe column, np.array, or pd.Series to be plotted. If np.array or pd.Series are used then it must have same length as dataframe. Values are used to color the plot. Ignored if color is also set.
- cmapstr (default None)
The name of a colormap recognized by matplotlib.
- colorstr (default None)
If specified, all objects will be colored uniformly.
- axmatplotlib.pyplot.Artist (default None)
axes on which to draw the plot
- caxmatplotlib.pyplot Artist (default None)
axes on which to draw the legend in case of color map.
- categoricalbool (default False)
If False, cmap will reflect numerical values of the column being plotted. For non-numerical columns, this will be set to True.
- legendbool (default False)
Plot a legend. Ignored if no column is given, or if color is given.
- schemestr (default None)
Name of a choropleth classification scheme (requires mapclassify). A mapclassify.MapClassifier object will be used under the hood. Supported are all schemes provided by mapclassify (e.g. ‘BoxPlot’, ‘EqualInterval’, ‘FisherJenks’, ‘FisherJenksSampled’, ‘HeadTailBreaks’, ‘JenksCaspall’, ‘JenksCaspallForced’, ‘JenksCaspallSampled’, ‘MaxP’, ‘MaximumBreaks’, ‘NaturalBreaks’, ‘Quantiles’, ‘Percentiles’, ‘StdMean’, ‘UserDefined’). Arguments can be passed in classification_kwds.
- kint (default 5)
Number of classes (ignored if scheme is None)
- vminNone or float (default None)
Minimum value of cmap. If None, the minimum data value in the column to be plotted is used.
- vmaxNone or float (default None)
Maximum value of cmap. If None, the maximum data value in the column to be plotted is used.
- markersizestr or float or sequence (default None)
Only applies to point geometries within a frame. If a str, will use the values in the column of the frame specified by markersize to set the size of markers. Otherwise can be a value to apply to all points, or a sequence of the same length as the number of points.
- figsizetuple of integers (default None)
Size of the resulting matplotlib.figure.Figure. If the argument axes is given explicitly, figsize is ignored.
- legend_kwdsdict (default None)
Keyword arguments to pass to matplotlib.pyplot.legend() or matplotlib.pyplot.colorbar(). Additional accepted keywords when scheme is specified:
- fmtstring
A formatting specification for the bin edges of the classes in the legend. For example, to have no decimals:
{"fmt": "{:.0f}"}
.- labelslist-like
A list of legend labels to override the auto-generated labels. Needs to have the same number of elements as the number of classes (k).
- categorieslist-like
Ordered list-like object of categories to be used for categorical plot.
- classification_kwdsdict (default None)
Keyword arguments to pass to mapclassify
- missing_kwdsdict (default None)
Keyword arguments specifying color options (as style_kwds) to be passed on to geometries with missing values in addition to or overwriting other style kwds. If None, geometries with missing values are not plotted.
- aspect‘auto’, ‘equal’ or float (default ‘auto’)
Set aspect of axis. If ‘auto’, the default aspect for map plots is ‘equal’; if however data are not projected (coordinates are long/lat), the aspect is by default set to 1/cos(df_y * pi/180) with df_y the y coordinate of the middle of the GeoDataFrame (the mean of the y range of bounding box) so that a long/lat square appears square in the middle of the plot. This implies an Equirectangular projection. It can also be set manually (float) as the ratio of y-unit to x-unit.
- **style_kwdsdict
Style options to be passed on to the actual plot function, such as
edgecolor
,facecolor
,linewidth
,markersize
,alpha
.
- Returns
- axmatplotlib axes instance
-
GeoDataFrame.
rename_geometry
(self, col, inplace=False)¶ Renames the GeoDataFrame geometry column to the specified name. By default yields a new object.
The original geometry column is replaced with the input.
- Parameters
- colnew geometry column label
- inplaceboolean, default False
Modify the GeoDataFrame in place (do not create a new object)
- Returns
- geodataframeGeoDataFrame
Examples
>>> df1 = df.rename_geometry('geom1') >>> df1.geometry.name 'geom1' >>> df.rename_geometry('geom1', inplace=True) >>> df.geometry.name 'geom1'
-
GeoDataFrame.
set_geometry
(self, col, drop=False, inplace=False, crs=None)¶ Set the GeoDataFrame geometry using either an existing column or the specified input. By default yields a new object.
The original geometry column is replaced with the input.
- Parameters
- colcolumn label or array
- dropboolean, default True
Delete column to be used as the new geometry
- inplaceboolean, default False
Modify the GeoDataFrame in place (do not create a new object)
- crspyproj.CRS, optional
Coordinate system to use. The value can be anything accepted by
pyproj.CRS.from_user_input()
, such as an authority string (eg “EPSG:4326”) or a WKT string. If passed, overrides both DataFrame and col’s crs. Otherwise, tries to get crs from passed col values or DataFrame.
- Returns
- GeoDataFrame
Examples
>>> df1 = df.set_geometry([Point(0,0), Point(1,1), Point(2,2)]) >>> df2 = df.set_geometry('geom1')
-
GeoDataFrame.
explode
(self)¶ Explode muti-part geometries into multiple single geometries.
Each row containing a multi-part geometry will be split into multiple rows with single geometries, thereby increasing the vertical size of the GeoDataFrame.
The index of the input geodataframe is no longer unique and is replaced with a multi-index (original index with additional level indicating the multiple geometries: a new zero-based index for each single part geometry per multi-part geometry).
- Returns
- GeoDataFrame
Exploded geodataframe with each single geometry as a separate entry in the geodataframe.
-
GeoDataFrame.
dissolve
(self, by=None, aggfunc='first', as_index=True)¶ Dissolve geometries within groupby into single observation. This is accomplished by applying the unary_union method to all geometries within a groupself.
Observations associated with each groupby group will be aggregated using the aggfunc.
- Parameters
- bystring, default None
Column whose values define groups to be dissolved
- aggfuncfunction or string, default “first”
Aggregation function for manipulation of data associated with each group. Passed to pandas groupby.agg method.
- as_indexboolean, default True
If true, groupby columns become index of result.
- Returns
- GeoDataFrame
-
GeoDataFrame.
__geo_interface__
¶ Returns a
GeoDataFrame
as a python feature collection.Implements the geo_interface. The returned python data structure represents the
GeoDataFrame
as a GeoJSON-likeFeatureCollection
.This differs from _to_geo() only in that it is a property with default args instead of a method
All pandas DataFrame
methods are also available, although they may
not operate in a meaningful way on the geometry
column and may not
return a GeoDataFrame
result even when it would be appropriate to
do so.
Testing¶
GeoPandas includes specific functions to test its objects.
-
geopandas.testing.
geom_equals
(this, that)¶ Test for geometric equality. Empty or missing geometries are considered equal.
- Parameters
- this, thatarrays of Geo objects (or anything that has an is_empty
attribute)
-
geopandas.testing.
geom_almost_equals
(this, that)¶ Test for ‘almost’ geometric equality. Empty or missing geometries considered equal.
This method allows small difference in the coordinates, but this requires coordinates be in the same order for all components of a geometry.
- Parameters
- this, thatarrays of Geo objects (or anything that has an is_empty
property)
-
geopandas.testing.
assert_geoseries_equal
(left, right, check_dtype=True, check_index_type=False, check_series_type=True, check_less_precise=False, check_geom_type=False, check_crs=True)¶ Test util for checking that two GeoSeries are equal.
- Parameters
- left, righttwo GeoSeries
- check_dtypebool, default False
If True, check geo dtype [only included so it’s a drop-in replacement for assert_series_equal].
- check_index_typebool, default False
Check that index types are equal.
- check_series_typebool, default True
Check that both are same type (and are GeoSeries). If False, will attempt to convert both into GeoSeries.
- check_less_precisebool, default False
If True, use geom_almost_equals. if False, use geom_equals.
- check_geom_typebool, default False
If True, check that all the geom types are equal.
- check_crs: bool, default True
If check_series_type is True, then also check that the crs matches.
-
geopandas.testing.
assert_geodataframe_equal
(left, right, check_dtype=True, check_index_type='equiv', check_column_type='equiv', check_frame_type=True, check_like=False, check_less_precise=False, check_geom_type=False, check_crs=True)¶ Check that two GeoDataFrames are equal/
- Parameters
- left, righttwo GeoDataFrames
- check_dtypebool, default True
Whether to check the DataFrame dtype is identical.
- check_index_type, check_column_typebool, default ‘equiv’
Check that index types are equal.
- check_frame_typebool, default True
Check that both are same type (and are GeoDataFrames). If False, will attempt to convert both into GeoDataFrame.
- check_likebool, default False
If true, ignore the order of rows & columns
- check_less_precisebool, default False
If True, use geom_almost_equals. if False, use geom_equals.
- check_geom_typebool, default False
If True, check that all the geom types are equal.
- check_crs: bool, default True
If check_frame_type is True, then also check that the crs matches.
Top-level Functions¶
|
A GeoDataFrame object is a pandas.DataFrame that has a column with geometry. |
|
A Series object designed to store shapely geometry objects. |
|
Returns a GeoDataFrame from a file or URL. |
|
Load a Parquet object from the file path, returning a GeoDataFrame. |
|
Load a Feather object from the file path, returning a GeoDataFrame. |
|
Returns a GeoDataFrame corresponding to the result of the query string, which must contain a geometry column in WKB representation. |
|
Spatial join of two GeoDataFrames. |
|
Perform spatial overlay between two GeoDataFrames. |
|
Clip points, lines, or polygon geometries to the mask extent. |
|
Geocode a set of strings and get a GeoDataFrame of the resulting points. |
|
Collect single part geometries into their Multi* counterpart |
|
Generate GeometryArray of shapely Point geometries from x, y(, z) coordinates. |
|
Get the path to the data file. |