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.
Unary Predicates
-
GeoSeries.
is_empty
¶ Returns a
Series
ofdtype('bool')
with valueTrue
for empty geometries.
-
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
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.
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.
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 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_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
in string or dictionary form or an EPSG code 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
- crsdict or str
Output projection parameters as string or in dictionary form.
- epsgint
EPSG code specifying output projection.
-
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.
- **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).
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 tablular data structure that contains a column
called geometry
which contains a GeoSeries`.
Currently, the following methods are implemented for a 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_postgis
(sql, con, geom_col='geom', crs=None, index_col=None, coerce_float=True, parse_dates=None, params=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.
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 a GeoSeries to a different coordinate reference system. The
crs
attribute on the current GeoSeries must be set. Eithercrs
in string or dictionary form or an EPSG code 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
- crsdict or str
Output projection parameters as string or in dictionary form.
- epsgint
EPSG code specifying output projection.
- inplacebool, optional, default: False
Whether to return a new GeoDataFrame or do the transformation in place.
-
GeoDataFrame.
to_file
(self, filename, driver='ESRI Shapefile', schema=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.
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.
-
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.
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().
- classification_kwdsdict (default None)
Keyword arguments to pass to mapclassify
- **style_kwdsdict
Color 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.
__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.
API Pages¶
|
A GeoDataFrame object is a pandas.DataFrame that has a column with geometry. |
|
A Series object designed to store shapely geometry objects. |
|
Perform spatial overlay between two polygons. |
|
Returns a GeoDataFrame from a file or URL. |
|
Spatial join of two GeoDataFrames. |
|
Geocode a set of strings and get a GeoDataFrame of the resulting points. |
|
Get the path to the data file. |