GeoPandas Repo Skill

Use this skill when a task needs package-specific guidance for GeoPandas, the Python library that extends pandas with Shapely geometry columns, CRS-aware GeoSeries/GeoDataFrame objects, vector I/O, spatial analysis, mapping, geocoding, and geometry-aware testing.

Start Here

• Package overview: shared GeoPandas concepts, base versus optional dependencies, object rules, and optional workflow matrix.
• Cross-cutting troubleshooting: install/import, optional dependency, CRS, geometry validity, and no-CLI issues.
• Repository provenance: source snapshot and refresh criteria for this generated skill.
• check_geopandas_environment.py: safe import/dependency and tiny GeoDataFrame/spatial-join smoke checker.

Installation and Import Check

GeoPandas requires Python 3.11+ for this snapshot. A base install should provide numpy, pandas, shapely, pyproj, pyogrio, and packaging.

import geopandas as gpd
from shapely.geometry import Point

gdf = gpd.GeoDataFrame({"name": ["a"], "geometry": [Point(0, 0)]}, crs="EPSG:4326")
assert gdf.crs.to_string() == "EPSG:4326"

For environment diagnostics from this skill directory:

python scripts/check_geopandas_environment.py --json

Sub-skill Routes

Task signal	Read
Constructing or repairing GeoDataFrame/GeoSeries, active geometry columns, CRS metadata, set_crs versus to_crs, missing/empty geometry, coordinate access, spatial-index basics	core-data-model
Reading or writing files, GeoJSON, GPKG, WKB/WKT, Arrow, Parquet, Feather, GeoParquet/GeoArrow, PostGIS, pyogrio/Fiona, bbox/mask/columns/rows filters	io-formats
Spatial joins, nearest joins, overlays, clips, dissolves, predicates, buffers, distance/area, invalid geometry repair, spatial-index queries, vector analysis pipelines	spatial-operations
Static .plot(), interactive .explore(), choropleths, folium/mapclassify/tile dependencies, geocoding, reverse geocoding, provider/network issues	mapping-geocoding
geopandas.testing assertions, expected GeoDataFrame fixtures, equality tolerances, focused pytest selection, optional dependency test triage, repository-maintainer validation	validation-testing

Workflow Order

1. Use core-data-model to create/repair objects and validate CRS/geometry quality.
2. Use io-formats to load inputs or persist outputs when file/database formats are involved.
3. Use spatial-operations for analysis and geometry transformations.
4. Use mapping-geocoding only when rendering maps or calling geocoding providers is part of the deliverable.
5. Use validation-testing to assert results or maintain the repository.

Common Decisions

• Use set_crs() only to assign known CRS metadata to existing coordinates; use to_crs() to transform coordinates.
• Reproject to a suitable projected CRS before metric distances, areas, buffers, nearest thresholds, or distance columns.
• Prefer base pyogrio I/O unless the task specifically needs optional Fiona behavior.
• Treat pyarrow, SQL/PostGIS, matplotlib, folium, mapclassify, geopy, and tile/basemap packages as optional workflow dependencies.
• Do not call real geocoding providers, database services, or remote URLs in smoke tests unless the user explicitly authorizes network/service use.
• GeoPandas is primarily a Python API package; route command-line requests to bundled diagnostic scripts or a small public-API wrapper.

Safety and Self-containment

The bundled references and scripts are sufficient for common GeoPandas operation without reopening the source checkout. Runtime scripts use tiny fixtures, temporary directories, or import checks and avoid network, credentials, destructive database writes, large notebooks, and benchmark-scale tasks by default.