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 the GeoSeries.

GeoSeries.bounds

Returns a DataFrame with columns minx, 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 of dtype('bool') with value True 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 of dtype('bool') with value True for features that are closed.

GeoSeries.is_simple

Returns a Series of dtype('bool') with value True for geometries that do not cross themselves.

This is meaningful only for LineStrings and LinearRings.

GeoSeries.is_valid

Returns a Series of dtype('bool') with value True for geometries that are valid.

Binary Predicates

GeoSeries.geom_almost_equals(self, other, decimal=6)

Returns a Series of dtype('bool') with value True 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 of dtype('bool') with value True 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 expression a.contains(b) == b.within(a) always evaluates to True.

Parameters
otherGeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if is contained.

GeoSeries.crosses(self, other)

Returns a Series of dtype('bool') with value True 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 of dtype('bool') with value True 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 of dtype('bool') with value True 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 of dtype('bool') with value True 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 of dtype('bool') with value True 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 of dtype('bool') with value True 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 expression a.within(b) == b.contains(a) always evaluates to True.

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 of dtype('bool') with value True 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.

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 by pyproj.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. Either crs or epsg 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-like FeatureCollection. Note that the features will have an empty properties 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 by pyproj.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. Either crs or epsg 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 of pandas.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. Either crs or epsg 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.

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. If False, the index(es) will not be written to the file. If None, 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. If False, the index(es) will not be written to the file. If None, 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-like FeatureCollection.

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

GeoDataFrame(*args, **kwargs)

A GeoDataFrame object is a pandas.DataFrame that has a column with geometry.

GeoSeries([data, index, crs])

A Series object designed to store shapely geometry objects.

read_file(filename[, bbox, mask, rows])

Returns a GeoDataFrame from a file or URL.

read_parquet(path[, columns])

Load a Parquet object from the file path, returning a GeoDataFrame.

read_feather(path[, columns])

Load a Feather object from the file path, returning a GeoDataFrame.

read_postgis(sql, con[, geom_col, crs, …])

Returns a GeoDataFrame corresponding to the result of the query string, which must contain a geometry column in WKB representation.

sjoin(left_df, right_df[, how, op, lsuffix, …])

Spatial join of two GeoDataFrames.

overlay(df1, df2[, how, make_valid, …])

Perform spatial overlay between two GeoDataFrames.

clip(gdf, mask[, keep_geom_type])

Clip points, lines, or polygon geometries to the mask extent.

tools.geocode(strings[, provider])

Geocode a set of strings and get a GeoDataFrame of the resulting points.

tools.collect(x[, multi])

Collect single part geometries into their Multi* counterpart

points_from_xy(x, y[, z, crs])

Generate GeometryArray of shapely Point geometries from x, y(, z) coordinates.

datasets.get_path(dataset)

Get the path to the data file.