From 2248d1cb2dfde82531981cdce1788fa56692bf70 Mon Sep 17 00:00:00 2001 From: Kelsey Jordahl Date: Sun, 7 Jul 2013 15:34:45 +0530 Subject: [PATCH] Filling out documentation for GeoSeries and GeoDataFrame --- doc/docs.rst | 192 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) diff --git a/doc/docs.rst b/doc/docs.rst index 9239e7c..ec22511 100644 --- a/doc/docs.rst +++ b/doc/docs.rst @@ -1,12 +1,204 @@ Documentation ============= +GeoPandas implements two main data structures, a ``GeoSeries`` and a +``GeoDataFrame``. These are subclasses of pandas ``Series`` and +``DataFrame``, respectively. + GeoSeries --------- +A ``GeoSeries`` contains a sequence of geometries. + +The ``GeoSeries`` class implements nearly all of the attributes and +methods of Shapely objects. When applied to a ``GeoSeries``, they +will apply elementwise to all geometries in the series. Binary +operations can be applied between two ``GeoSeries``, in which case the +operation is carried out elementwise. The two series will be aligned +by matching indices. Binary operations can also be applied to a +single geometry, in which case the operation is carried out for each +element of the series with that geometry. In either case, a +``Series`` or a ``GeoSeries`` will be returned, as appropriate. + +The following Shapely methods and attributes are available on +``GeoSeries`` objects: + +.. attribute:: GeoSeries.area + + Returns a ``Series`` containing the area of each geometry in the ``GeoSeries``. + +.. attribute:: GeoSeries.bounds + + Returns a ``DataFrame`` with columns ``minx``, ``miny``, ``maxx``, + ``maxy`` values containing the bounds for each geometry. + NOTE: This behavior may change in future versions. + +.. attribute:: GeoSeries.length + + Returns a ``Series`` containing the length of each geometry. + +.. attribute:: GeoSeries.geom_type + + Returns a ``Series`` of strings specifying the `Geometry Type` of + each object. + +.. method:: GeoSeries.distance(other) + + Returns a ``Series`` containing the minimum distance to the `other` + ``GeoSeries`` (elementwise) or geometric object. + +.. method:: GeoSeries.representative_point() + + Returns a ``GeoSeries`` of (cheaply computed) points that are + guaranteed to be within each geometry. + +`Unary Predicates` + +.. attribute:: GeoSeries.is_empty + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for + empty geometries. + +.. attribute:: GeoSeries.is_ring + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for + features that are closed. + +.. attribute:: GeoSeries.is_simple + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for + geometries that do not cross themselves (meaningful only for + `LineStrings` and `LinearRings`). + +.. attribute:: GeoSeries.is_valid + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for + geometries that are valid. + +`Binary Predicates` + +.. method:: GeoSeries.almost_equals(other[, decimal=6]) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + each object is approximately equal to the `other` at all + points to specified `decimal` place precision. (See also :meth:`equals`) + +.. method:: GeoSeries.contains(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + each object's `interior` contains the `boundary` and + `interior` of the other object and their boundaries do not touch at all. + +.. method:: GeoSeries.crosses(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + the `interior` of each object 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. + +.. method:: GeoSeries.disjoint(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + the `boundary` and `interior` of each object does not + intersect at all with those of the other. + +.. method:: GeoSeries.equals(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + if the set-theoretic `boundary`, `interior`, and `exterior` + of each object coincides with those of the other. + +.. method:: GeoSeries.intersects(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + if the `boundary` and `interior` of each object intersects in + any way with those of the other. + +.. method:: GeoSeries.touches(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + the objects have at least one point in common and their + interiors do not intersect with any part of the other. + +.. method:: GeoSeries.within(other) + + Returns a ``Series`` of ``dtype('bool')`` with value ``True`` if + each object's `boundary` and `interior` intersect only + with the `interior` of the other (not its `boundary` or `exterior`). + (Inverse of :meth:`contains`) + +`Set-theoretic Methods` + +.. attribute:: GeoSeries.boundary + + Returns a ``GeoSeries`` of lower dimensional objects representing + each geometries's set-theoretic `boundary`. + +.. attribute:: GeoSeries.centroid + + Returns a ``GeoSeries`` of points for each geometric centroid. + +.. method:: GeoSeries.difference(other) + + Returns a ``GeoSeries`` of the points in each geometry that + are not in the *other* object. + +.. method:: GeoSeries.intersection(other) + + Returns a ``GeoSeries`` of the intersection of each object with the `other` + geometric object. + +.. method:: GeoSeries.symmetric_difference(other) + + Returns a ``GeoSeries`` of the points in each object not in the `other` + geometric object, and the points in the `other` not in this object. + +.. method:: GeoSeries.union(other) + + Returns a ``GeoSeries`` of the union of points from each object and the + `other` geometric object. + + +Additionally, the following methods are implemented: + +.. method:: GeoSeries.plot(colormap='Set1') + + Generate a plot of the geometries in the ``GeoSeries``. + ``colormap`` can be any recognized by matplotlib, but discrete + colormaps such as ``Accent``, ``Dark2``, ``Paired``, ``Pastel1``, + ``Pastel2``, ``Set1``, ``Set2``, or ``Set3`` are recommended. + +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 +``copy()``, ``align()``, ``isnull()`` 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 only the following methods are implemented for a ``GeoDataFrame``: + +.. method:: GeoDataFrame.from_file() + + Load a ``GeoDataFrame`` from a file from any format recognized by + `fiona`_. + +.. method:: GeoDataFrame.plot() + + Generate a plot of the geometries in the ``GeoDataFrame``. + Currently calls ``GeoSeries.plot()`` on the ``geometry`` column, + though in the future this will be able to color the geometries by + data values from another column. + +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. Examples --------