geopandas-knowledge-patch

# GeoPandas Compatibility Guidance Use this skill to make GeoPandas dependency, migration, geometry-operation, I/O, database, overlay, and visualization decisions. ## Working method 1. Inspect the project's GeoPandas, Python, pandas, NumPy, pyproj, and optional dependency constraints. 2. Read the reference file that matches the task before changing code. 3. Check removed APIs and behavior changes before diagnosing a regression. 4. Preserve CRS and geometry dtype explicitly when testing pandas interop. 5. Treat ordering as significant only where the relevant API guarantees it. 6. Add focused tests for the compatibility case being changed. ## Reference index | Reference | Topics | | --- | --- | | [Compatibility and pandas interop](references/compatibility-and-pandas.md) | Dependency floors, removed methods, constructors, CRS retention, geometry-column removal, pandas 3 behavior | | [Geometry operations](references/geometry-operations.md) | Spatial indexes, union and dissolve, coverage tools, validity repair, M coordinates, sampling, geometry aggregation | | [I/O and databases](references/io-and-databases.md) | Arrow conversion, Parquet and Feather, file masks, feature ingestion, PostGIS | | [Overlays and exploration](references/overlays-and-exploration.md) | Identity and empty overlays, pandas geometry accessor, explore legend labels | ## Breaking changes and dependency floors Require these core versions: - Python 3.10 or newer - pandas 2.0 or newer - NumPy 1.24 or newer - pyproj 3.5 or newer The optional versions tested at minimum are Fiona 1.8.21, SciPy 1.9, matplotlib 3.7, mapclassify 2.5, folium 0.12, and SQLAlchemy 2.0. Older optional versions may work, but are unsupported. Replace removed `GeoSeries` methods: ```python # Removed: series.geom_almost_equals(other) matches = series.geom_equals_exact(other, tolerance) ``` Do not call `GeoSeries.select`; it was removed because supported pandas versions no longer provide the corresponding method. Deleting the last geometry column changes the container type: ```python del gdf["geometry"] # gdf is now a pandas DataFrame when no geometry columns remain. ``` Read [Compatibility and pandas interop](references/compatibility-and-pandas.md) when upgrading dependencies or debugging dtype, CRS, construction, or missing-value behavior. ## Spatial-index result formats Choose the `SpatialIndex.query` representation with `output_format`: ```python dense_hits = frame.sindex.query( queries.geometry, output_format="dense", ) sparse_hits = frame.sindex.query( queries.geometry, output_format="sparse", ) ``` The sparse boolean representation requires SciPy. Select dense or sparse deliberately rather than assuming one representation. ## Union and dissolve controls Apply a precision grid during union or grouped dissolve: ```python merged = frame.geometry.union_all(grid_size=0.01) dissolved = frame.dissolve("group", grid_size=0.01) ``` Select the disjoint-subset union algorithm where appropriate: ```python merged = frame.geometry.union_all(method="disjoint_subset") dissolved = frame.dissolve( "group", method="disjoint_subset", ) ``` See [Geometry operations](references/geometry-operations.md) for the related coverage, repair, coordinate, sampling, and aggregation APIs. ## Polygonal coverage and repair Validate and simplify polygonal coverages with the coverage-specific methods: ```python valid = frame.geometry.is_valid_coverage() invalid_edges = frame.geometry.invalid_coverage_edges() simplified = frame.geometry.simplify_coverage(0.5) ``` Control geometry repair with `method` and `keep_collapsed`: ```python fixed = frame.geometry.make_valid( method="linework", keep_collapsed=True, ) ``` Choose these options explicitly when the repair algorithm or treatment of collapsed components matters. ## Measured coordinates Use `m` and `has_m` for measured-coordinate access: ```python measures = points.m has_measures = frame.geometry.has_m ``` Include M values when extracting coordinates: ```python coordinates = frame.geometry.get_coordinates( include_m=True, ) ``` ## Arrow conversion Pass pandas conversion controls through Arrow-backed readers and constructors with `to_pandas_kwargs`: ```python frame = geopandas.read_parquet( "data.parquet", to_pandas_kwargs={"use_threads": False}, ) ``` The option is accepted by `from_arrow`, `read_parquet`, and `read_feather`. It also applies when non-geometry Parquet columns contain list or struct data. Read [I/O and databases](references/io-and-databases.md) before changing Arrow conversion, file-mask CRS handling, feature ingestion, or PostGIS code. ## Point sampling Use list-like `size` with `pointpats` methods for per-geometry sample counts, and use `rng` for reproducible sampling: ```python sampled = geometries.sample_points( size=[10, 20], method="cluster_poisson", rng=42, ) ``` Do not assume sampled points are ordered by x-coordinate. Generated points are no longer sorted that way. ## Overlay and exploration checks Identity overlays support matching input column names. Empty-input overlays handle `keep_geom_type` more gracefully. For categorical or boolean exploration maps, provide custom legend labels: ```python result = frame.explore( column="category", legend_kwds={"labels": ["First", "Second"]}, ) ``` Read [Overlays and exploration](references/overlays-and-exploration.md) for overlay edge cases and pandas Series geometry access. ## Verification checklist - Confirm core and optional dependency constraints. - Search for removed `select` and `geom_almost_equals` calls. - Test CRS retention after pandas operations. - Test the result type after removing geometry columns. - Exercise missing geometries and missing string values. - Check sparse-index paths with SciPy installed. - Test union precision and algorithm selection separately. - Validate Arrow conversion with representative nested columns. - Verify overlay behavior with duplicate column names and empty inputs. - Avoid assertions that depend on sampled-point x ordering.