GeoPandas Documentation

GeoPandas extends pandas to support geographic data. It provides two primary data structures that are subclasses of standard pandas objects:

• GeoSeries: A subclass of pandas.Series designed to hold geometric data.
• GeoDataFrame: A subclass of pandas.DataFrame that allows for tabular data with a geometry column.

These objects can operate on shapely geometry objects and perform various geometric operations.

GeoPandas is an open source Python library designed to make working with geospatial data easier. It extends the pandas data structures to allow spatial operations on geometric types.

Key characteristics:

• Spatial Operations: Performs geometric operations using shapely.
• File Access: Uses pyogrio for reading and writing geospatial files.
• Visualization: Uses matplotlib for plotting geospatial data.
• Functionality: Provides a high-level interface for multiple geometries, enabling Python-based spatial operations that would typically require a spatial database like PostGIS.

The public API of GeoPandas consists of all classes and functions exposed in the geopandas.* namespace, as well as those explicitly listed in the official API reference.

Note on Private Modules: The geopandas.array and geopandas.base modules are considered private. Stable functionality in these modules is not guaranteed, and you should avoid relying on them for production code.

GeoPandas documentation is organized into four primary sections to help users at different stages of expertise:

• User Guide: Explains basic functionality and core concepts.
• Advanced Guide: Covers complex topics for users who already understand the basics.
• Examples: A gallery of practical usage examples.
• API Reference: Detailed technical documentation for every class, method, function, and attribute implemented by GeoPandas.

GeoPandas relies on several core libraries to provide its geospatial capabilities. Understanding these dependencies helps in troubleshooting installation issues or understanding how GeoPandas handles specific tasks:

• pandas: Provides the fundamental data structures for tabular and time-series data.
• Shapely: Handles manipulation and analysis of planar geometric objects (backed by GEOS).
• pyogrio: Provides the API for reading and writing vector data files (like Shapefile, GeoPackage, and GeoJSON) using GDAL.
• pyproj: Manages cartographic projections and coordinate transformations (interface to PROJ).

A GeoSeries is a subclass of pandas.Series that acts as a vector where each entry is a set of geometric shapes (Shapely objects).

Supported geometric types include:

• Points / Multi-Points
• Lines / Multi-Lines
• Polygons / Multi-Polygons

Note that entries in a GeoSeries do not need to be of the same geometric type, though some export operations may require uniformity.

GeoPandas documentation is located in the doc folder. Changes are made within the doc/source directory. The project uses a mixture of reStructuredText (.rst) and MyST (.md) syntax. Docstrings must follow the Numpy Docstring standard. Jupyter notebooks used for examples should be stored without output and are processed via nbsphinx.

To verify your documentation changes, build the HTML version using Sphinx:

1. Navigate to the doc folder.
2. Run make html.
3. View the results in doc/build/html.

If you encounter errors, you can build the documentation in a dedicated environment using the environment.yml file provided in the doc folder:

cd doc
conda env create -f environment.yml
conda activate geopandas_docs
python -m ipykernel install --user --name geopandas_docs
make html

GeoPandas supports the Parquet format, which is efficient for large datasets.

• Use geopandas.read_parquet() to read a Parquet file into a GeoDataFrame.
• Use GeoDataFrame.to_parquet() to write a GeoDataFrame to a Parquet file.

Always create a new feature branch for your changes to keep your main branch clean and production-ready. Use git checkout -b <branch-name> to create and switch to a new branch. To update your branch with the latest changes from the upstream main branch, use git fetch upstream followed by git rebase upstream/main.

git checkout -b shiny-new-feature

# To update your branch with latest upstream changes:
git fetch upstream
git rebase upstream/main

You can use set-theoretic operations to find the intersection or difference between geometries. In a GeoDataFrame, you can access the geometry column via .geometry or use the shorthand operators:

• Intersection: Use .intersection() or the & operator.
• Difference: Use .difference() or the - operator.

Example: boros.geometry - mp calculates the difference between the borough geometries and a multipolygon mp.