diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 6611eed..a384ab2 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,9 +1,10 @@ -Contributing -============ +Contributing to GeoPandas +========================= + (Contribution guidelines largely copied from `pandas `_) Overview ----------- +-------- Contributions to GeoPandas are very welcome. They are likely to be accepted more quickly if they follow these guidelines. @@ -14,7 +15,7 @@ readable code. Performance matters, but not at the expense of those goals. In general, GeoPandas follows the conventions of the pandas project -where applicable. +where applicable. In particular, when submitting a pull request: @@ -37,7 +38,7 @@ In particular, when submitting a pull request: code base. Use modern python idioms when possible that are compatibile with both major versions, and use the `six `_ library where helpful to smooth - over the differences. Use `from __future__ import` statements where + over the differences. Use ``from __future__ import`` statements where appropriate. Test code locally in both python 2 and python 3 when possible (all supported versions will be automatically tested on Travis CI). @@ -54,8 +55,7 @@ In particular, when submitting a pull request: Seven Steps for Contributing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are seven basic steps to contributing to *geopandas* - +There are seven basic steps to contributing to *geopandas*: 1) Fork the *geopandas* git repository 2) Create a development environment @@ -65,8 +65,7 @@ There are seven basic steps to contributing to *geopandas* 6) Update the documentation 7) Submit a Pull Request -Each of these 7 steps is detailed below. - +Each of these 7 steps is detailed below. 1) Forking the *geopandas* repository using Git @@ -153,29 +152,26 @@ after updating. --------------------------------------- A development environment is a virtual space where you can keep an independent installation of *geopandas*. This makes it easy to keep both a stable version of python in one place you use for work, and a development -version (which you may break while playing with code) in another. +version (which you may break while playing with code) in another. -An easy way to create a *geopandas** development environment is as follows. +An easy way to create a *geopandas* development environment is as follows: -- Install either :ref:`Anaconda ` or :ref:`miniconda ` +- Install either `Anaconda `_ or + `miniconda `_ - Make sure that you have :ref:`cloned the repository ` - ``cd`` to the *geopandas** source directory Tell conda to create a new environment, named ``geopandas_dev``, or any other name you would like for this environment, by running:: - conda create -n geopandas_dev + conda create -n geopandas_dev For a python 3 environment:: - conda create -n geopandas_dev python=3 - -.. warning:: - - If you are on Windows, see :ref:`here for a fully compliant Windows environment `. + conda create -n geopandas_dev python=3.4 This will create the new environment, and not touch any of your existing environments, -nor any existing python installation. +nor any existing python installation. To work in this environment, Windows users should ``activate`` it as follows:: @@ -197,39 +193,14 @@ To return to you home root environment:: See the full conda docs `here `__. -At this point you can easily do a *development* install, as detailed in the next section. - -.. _contributing.windows: - -Creating a Windows development environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To build on Windows, you need to have compilers installed to build the extensions. You will need to install the appropriate Visual Studio compilers, VS 2008 for Python 2.7, VS 2010 for 3.4, and VS 2015 for Python 3.5. - -For Python 2.7, you can install the ``mingw`` compiler which will work equivalently to VS 2008:: - - conda install -n geopandas_dev libpython - -or use the `Microsoft Visual Studio VC++ compiler for Python `__. Note that you have to check the ``x64`` box to install the ``x64`` extension building capability as this is not installed by default. - -For Python 3.4, you can download and install the `Windows 7.1 SDK `__. Read the references below as there may be various gotchas during the installation. - -For Python 3.5, you can download and install the `Visual Studio 2015 Community Edition `__. - -Here are some references: - -- https://github.com/conda/conda-recipes/wiki/Building-from-Source-on-Windows-32-bit-and-64-bit -- https://cowboyprogrammer.org/building-python-wheels-for-windows/ -- https://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/ -- https://support.enthought.com/hc/en-us/articles/204469260-Building-Python-extensions-with-Canopy - - - +At this point you can easily do a *development* install, as detailed in the next sections. 3) Installing Dependencies ---------------------------- +-------------------------- -To run *geopandas* in an development environment, you must first install *geopandas*'s dependencies. We suggest doing so using the following commands (executed after your development environment has been activated):: +To run *geopandas* in an development environment, you must first install +*geopandas*'s dependencies. We suggest doing so using the following commands +(executed after your development environment has been activated):: conda install -c conda-forge fiona shapely pyproj rtree conda install pandas @@ -238,15 +209,14 @@ To run *geopandas* in an development environment, you must first install *geopan This should install all necessary dependencies. 4) Making a development build -------------------------------------- +----------------------------- -Once dependencies are in place, make an in-place build by navigating to the git clone of the *geopandas* repository and running:: +Once dependencies are in place, make an in-place build by navigating to the git +clone of the *geopandas* repository and running:: python setup.py develop - - 5) Making changes and writing tests ------------------------------------- @@ -270,32 +240,14 @@ extensions in `numpy.testing Writing tests ~~~~~~~~~~~~~ -All tests should go into the ``tests`` subdirectory of the specific package. -This folder contains many current examples of tests, and we suggest looking to these for -inspiration. +All tests should go into the ``tests`` directory. This folder contains many +current examples of tests, and we suggest looking to these for inspiration. -The ``.util`` module has many special ``assert`` functions that -make it easier to make statements about whether Series or DataFrame objects are -equivalent. The easiest way to verify that your code is correct is to +The ``.util`` module has some special ``assert`` functions that +make it easier to make statements about whether GeoSeries or GeoDataFrame +objects are equivalent. The easiest way to verify that your code is correct is to explicitly construct the result you expect, then compare the actual result to -the expected correct result:: - - def test_pivot(self): - data = { - 'index' : ['A', 'B', 'C', 'C', 'B', 'A'], - 'columns' : ['One', 'One', 'One', 'Two', 'Two', 'Two'], - 'values' : [1., 2., 3., 3., 2., 1.] - } - - frame = DataFrame(data) - pivoted = frame.pivot(index='index', columns='columns', values='values') - - expected = DataFrame({ - 'One' : {'A' : 1., 'B' : 2., 'C' : 3.}, - 'Two' : {'A' : 1., 'B' : 2., 'C' : 3.} - }) - - assert_frame_equal(pivoted, expected) +the expected correct result, using eg the function ``assert_geoseries_equal``. Running the test suite ~~~~~~~~~~~~~~~~~~~~~~ @@ -306,22 +258,24 @@ install *geopandas*) by typing:: nosetests -v 6) Updating the Documentation ------------------------------- +----------------------------- -*geopandas* documentation resides in the `doc` folder. Changes to the docs are make by modifying the appropriate file in the `source` folder within `doc`. *geopandas* docs us reStructuredText syntax, `which is explained here `_. +*geopandas* documentation resides in the `doc` folder. Changes to the docs are +make by modifying the appropriate file in the `source` folder within `doc`. +*geopandas* docs us reStructuredText syntax, `which is explained here `_ +and the docstrings follow the `Numpy Docstring standard `_. Once you have made your changes, you can build the docs by navigating to the `doc` folder and typing:: make html -The resulting html pages will be located in `doc/build/html`. +The resulting html pages will be located in `doc/build/html`. 7) Submitting a Pull Request ------------------------------ -Once you've made changes and pushed them to your forked repository, you then submit a pull request to have them integrated into the *geopandas* code base. You can find pull request (or PR) tutorials here: - -* `GitHub's Help Docs `_ -* `Atlassian `_ +Once you've made changes and pushed them to your forked repository, you then +submit a pull request to have them integrated into the *geopandas* code base. +You can find a pull request (or PR) tutorial in the `GitHub's Help Docs `_. diff --git a/doc/source/data_structures.rst b/doc/source/data_structures.rst index a49b759..740429f 100644 --- a/doc/source/data_structures.rst +++ b/doc/source/data_structures.rst @@ -17,11 +17,11 @@ GeoPandas implements two main data structures, a ``GeoSeries`` and a GeoSeries --------- -A ``GeoSeries`` is essentially a vector where each entry in the vector +A ``GeoSeries`` is essentially a vector where each entry in the vector is a set of shapes corresponding to one observation. An entry may consist -of only one shape (like a single polygon) or multiple shapes that are +of only one shape (like a single polygon) or multiple shapes that are meant to be thought of as one observation (like the many polygons that -make up the State of Hawaii or a country like Indonesia). +make up the State of Hawaii or a country like Indonesia). *geopandas* has three basic classes of geometric objects (which are actually *shapely* objects): @@ -29,7 +29,7 @@ make up the State of Hawaii or a country like Indonesia). * Lines / Multi-Lines * Polygons / Multi-Polygons -Note that all entries in a ``GeoSeries`` need not be of the same geometric type, although certain export operations will fail if this is not the case. +Note that all entries in a ``GeoSeries`` need not be of the same geometric type, although certain export operations will fail if this is not the case. Overview of Attributes and Methods ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -44,9 +44,9 @@ 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. -A short summary of a few attributes and methods for GeoSeries is -presented here, and a full list can be found in the :doc:`all attributes and methods page `. -There is also a family of methods for creating new shapes by expanding +A short summary of a few attributes and methods for GeoSeries is +presented here, and a full list can be found in the :doc:`all attributes and methods page `. +There is also a family of methods for creating new shapes by expanding existing shapes or applying set-theoretic operations like "union" described in :doc:`geometric manipulations `. @@ -55,7 +55,7 @@ Attributes * ``area``: shape area (units of projection -- see :doc:`projections `) * ``bounds``: tuple of max and min coordinates on each axis for each shape * ``total_bounds``: tuple of max and min coordinates on each axis for entire GeoSeries -* ``geom_type``: type of geometry. +* ``geom_type``: type of geometry. * ``is_valid``: tests if coordinates make a shape that is reasonable geometric shape (`according to this `_). Basic Methods @@ -63,7 +63,7 @@ Basic Methods * ``distance(other)``: returns ``Series`` with minimum distance from each entry to ``other`` * ``centroid``: returns ``GeoSeries`` of centroids -* ``representative_point()``: returns ``GeoSeries``of points that are guaranteed to be within each geometry. It does **NOT** return centroids. +* ``representative_point()``: returns ``GeoSeries`` of points that are guaranteed to be within each geometry. It does **NOT** return centroids. * ``to_crs()``: change coordinate reference system. See :doc:`projections ` * ``plot()``: plot ``GeoSeries``. See :doc:`mapping `. @@ -78,26 +78,34 @@ Relationship Tests GeoDataFrame ------------ -A ``GeoDataFrame`` is a tablular data structure that contains a ``GeoSeries``. +A ``GeoDataFrame`` is a tabular data structure that contains a ``GeoSeries``. -The most important property of a ``GeoDataFrame`` is that it always has one ``GeoSeries`` column that holds a special status. This ``GeoSeries`` is referred to as the ``GeoDataFrame``'s "geometry". When a spatial method is applied to a ``GeoDataFrame`` (or a spatial attribute like ``area`` is called), this commands will always act on the "geometry" column. +The most important property of a ``GeoDataFrame`` is that it always has one ``GeoSeries`` column that holds a special status. This ``GeoSeries`` is referred to as the ``GeoDataFrame``'s "geometry". When a spatial method is applied to a ``GeoDataFrame`` (or a spatial attribute like ``area`` is called), this commands will always act on the "geometry" column. -The "geometry" column -- no matter its name -- can be accessed through the ``geometry`` attribute (``gdf.geometry``), and the name of the ``geometry`` column can be found by typing ``gdf.geometry.name``. +The "geometry" column -- no matter its name -- can be accessed through the ``geometry`` attribute (``gdf.geometry``), and the name of the ``geometry`` column can be found by typing ``gdf.geometry.name``. -A ``GeoDataFrame`` may also contain other ``GeoSeries``, but only one ``GeoSeries`` can be the active geometry at a time. To change which ``GeoSeries`` is the geometry, use the ``set_geometry`` method: +A ``GeoDataFrame`` may also contain other columns with geometrical (shapely) objects, but only one column can be the active geometry at a time. To change which column is the active geometry column, use the ``set_geometry`` method. -.. ipython:: python - - #Plot countries: +An example using the ``worlds`` GeoDataFrame: + +.. ipython:: python + + world.head() + #Plot countries @savefig world_borders.png width=3in world.plot(); - # Check geometry. - # Currently, the column named "borders" with country - # borders is the active geometry column. +Currently, the column named "borders" with country borders is the active +geometry column: + +.. ipython:: python + world.geometry.name - # Create centroids and make it the geometry +Now, we create centroids and make it the geometry: + +.. ipython:: python + world['centroid_column'] = world.centroid world = world.set_geometry('centroid_column') @@ -105,17 +113,15 @@ A ``GeoDataFrame`` may also contain other ``GeoSeries``, but only one ``GeoSerie world.plot(); -**Note:** A ``GeoDataFrame`` keeps track of the active column by name, so if you rename the active geometry column, you must also reset the geometry: +**Note:** A ``GeoDataFrame`` keeps track of the active column by name, so if you rename the active geometry column, you must also reset the geometry:: gdf = gdf.rename(columns={'old_name': 'new_name'}).set_geometry('new_name') **Note 2:** Somewhat confusingly, by default when you use the ``read_file`` command, the column containing spatial objects from the file is named "geometry" by default, and will be set as the active geometry column. However, despite using the same term for the name of the column and the name of the special attribute that keeps track of the active column, they are distinct. You can easily shift the active geometry column to a different ``GeoSeries`` with the ``set_geometry`` command. Further, ``gdf.geometry`` will always return the active geometry column, *not* the column named ``geometry``. If you wish to call a column named "geometry", and a different column is the active geometry column, use ``gdf['geometry']``, not ``gdf.geometry``. Attributes and Methods -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~ Any of the attributes calls or methods described for a ``GeoSeries`` will work on a ``GeoDataFrame`` -- effectively, they are just applied to the "geometry" ``GeoSeries``. However, ``GeoDataFrames`` also have a few extra methods for input and output which are described on the :doc:`Input and Output ` page and for geocoding with are described in :doc:`Geocoding `. - - diff --git a/doc/source/index.rst b/doc/source/index.rst index 9b7abfa..17d8c81 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -35,7 +35,7 @@ such as PostGIS. Merging Data Geocoding Reference to All Attributes and Methods - Contributing to Geopandas + Contributing to GeoPandas About Indices and tables @@ -44,4 +44,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/doc/source/install.rst b/doc/source/install.rst index 7effef5..4153f5a 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -31,39 +31,31 @@ Dependencies Installation via `conda` should also install all dependencies, but a complete list is as follows: -- `numpy`_ -- `pandas`_ (version 0.13 or later) -- `shapely`_ -- `fiona`_ -- `six`_ -- `pyproj`_ +- `numpy`_ +- `pandas`_ (version 0.13 or later) +- `shapely`_ +- `fiona`_ +- `six`_ +- `pyproj`_ -Further, optional dependencies are: - -- `geopy`_ 0.99 (optional; for geocoding) -- `psycopg2`_ (optional; for PostGIS connection) +Further, optional dependencies are: + +- `geopy`_ 0.99 (optional; for geocoding) +- `psycopg2`_ (optional; for PostGIS connection) - `rtree`_ (optional; spatial index to improve performance) -For plotting, these additional packages may be used: - -- `matplotlib`_ -- `descartes`_ -- `pysal`_ - +For plotting, these additional packages may be used: + +- `matplotlib`_ +- `descartes`_ +- `pysal`_ + These can be installed independently via the following set of commands:: conda install -c conda-forge fiona shapely pyproj rtree conda install pandas - - - - - -.. toctree:: - :maxdepth: 2 - .. _PyPI: https://pypi.python.org/pypi/geopandas .. _GitHub: https://github.com/geopandas/geopandas diff --git a/doc/source/io.rst b/doc/source/io.rst index a19b327..65f33f0 100644 --- a/doc/source/io.rst +++ b/doc/source/io.rst @@ -7,23 +7,22 @@ Reading and Writing Files Reading Spatial Data --------------------- -*geopandas* can read almost any vector-based spatial data format including ESRI shapefile, GeoJSON files and more using the command: +*geopandas* can read almost any vector-based spatial data format including ESRI shapefile, GeoJSON files and more using the command:: gpd.read_file() -which returns a GeoDataFrame object. (This is possible because *geopandas* makes use of the great `fiona `_ library, which in turn makes use of a massive open-source program called `GDAL/OGR `_ designed to facilitate spatial data transformations). +which returns a GeoDataFrame object. (This is possible because *geopandas* makes use of the great `fiona `_ library, which in turn makes use of a massive open-source program called `GDAL/OGR `_ designed to facilitate spatial data transformations). -Any arguments passed to ``read_file()`` after the file name will be passed directly to ``fiona.open``, which does the actual data importation. In general, ``read_file`` is pretty smart and should do what you want without extra arguments, but for more help, type: +Any arguments passed to ``read_file()`` after the file name will be passed directly to ``fiona.open``, which does the actual data importation. In general, ``read_file`` is pretty smart and should do what you want without extra arguments, but for more help, type:: import fiona; help(fiona.open) Among other things, one can explicitly set the driver (shapefile, GeoJSON) with the ``driver`` keyword, or pick a single layer from a multi-layered file with the ``layer`` keyword. -*geopandas* can also get data from a PostGIS database using the ``read_postgis()`` command. +*geopandas* can also get data from a PostGIS database using the ``read_postgis()`` command. Writing Spatial Data --------------------- -GeoDataFrames can be exported to many different standard formats using the ``GeoDataFrame.to_file()`` method. For a full list of supported formats, type ``import fiona; fiona.supported_drivers``. - +GeoDataFrames can be exported to many different standard formats using the ``GeoDataFrame.to_file()`` method. For a full list of supported formats, type ``import fiona; fiona.supported_drivers``.