AGENT SKILL

geopandas

Guidance and local audit tools for Python workflows that directly use GeoPandas GeoSeries, GeoDataFrame, spatial operations, or vector-data I/O.

License 许可
MIT
最近更新
2026-10-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
geopandas
license
MIT
metadata
{ "version": "1.0.0", "last-reviewed": "2026-07-23" }
description
Guidance and local audit tools for Python workflows that directly use GeoPandas GeoSeries, GeoDataFrame, spatial operations, or vector-data I/O.

02 资源文件 13

03 SKILL.md 正文

GeoPandas

Use GeoPandas for planar vector data represented as pandas-like GeoSeries and GeoDataFrame objects. This skill targets stable GeoPandas 1.1.4 (released 2026-06-26), not the unreleased 1.2 documentation.

Reproducible environment

GeoPandas 1.1.4 requires Python 3.10+; its tagged source requires NumPy >=1.24, pandas >=2.0, Shapely >=2.0, pyproj >=3.5, pyogrio >=0.7.2, and packaging. This exact Python 3.12 snapshot was smoke-tested on 2026-07-23:

uv venv --python 3.12
uv pip install \
  "geopandas==1.1.4" \
  "numpy==2.5.1" \
  "pandas==3.0.5" \
  "shapely==2.1.2" \
  "pyproj==3.7.2" \
  "pyogrio==0.13.0" \
  "pyarrow==25.0.0" \
  "packaging==26.2"

Keep optional plotting and PostGIS packages pinned in the project lock as well. Do not mix binary geospatial packages from incompatible package channels.

Safety and privacy contract

  • Treat exact coordinates, addresses, parcel boundaries, trajectories, and small-area joins as sensitive. Default reports to counts, categories, coarse extents, and redacted identifiers. Generalize before publication.
  • Never automatically load a URL, cloud URI, GDAL /vsi* path, archive, or geocode an address. Obtain explicit approval, validate provenance and hashes, then stage an unpacked local file in an isolated workspace.
  • GDAL/OGR drivers, GEOS, PROJ, pyogrio, Shapely, pyproj, and their wheels are a native-code trust boundary. Prefer official wheels/conda-forge, record native versions, restrict drivers, and process untrusted data in a sandbox.
  • Do not open macro-enabled office files or nested archives through permissive GDAL drivers. The bundled CLIs use an extension allowlist and reject archives.
  • Read only named database secrets such as GEOPANDAS_POSTGIS_PASSWORD; use a secret manager or scoped environment variable. Never embed a password in a URL or source, print an engine/URL, or dump the environment.
  • Every derived artifact needs source hashes/versions, CRS, operation parameters, predicate, join cardinality, precision/repair choices, and row-count checks.

Correctness gates

Apply these gates before trusting a result:

  1. Identity and provenance — identify the source layer, stable feature key, duplicate IDs, row count, geometry column, parser/driver, and content hash.
  2. Geometry state — count null, empty, invalid, mixed, Z/M, and collapsed geometries separately. None is missing; an empty Shapely geometry is real.
  3. CRS semantics — require CRS metadata. set_crs() assigns metadata; to_crs() transforms coordinates. Never guess a CRS from coordinate ranges.
  4. Units and operation — GeoPandas is planar. Geographic coordinates are angular; do not use them directly for buffer, distance, area, nearest joins, precision grids, or tolerances. Choose a fit-for-purpose local/equal-area CRS or a geodesic method.
  5. Transform quality — inspect axis order, area of use, datum pipeline, expected accuracy, ballpark status, and missing grids. Keep PROJ network disabled unless the user explicitly approves grid retrieval.
  6. Topology and precision — validate before and after repair/overlay. Pick a precision grid from source accuracy and CRS units; arbitrary snapping can collapse features or create bias.
  7. Cardinality — state expected one-to-one, one-to-many, or many-to-many behavior before merge, sjoin, or sjoin_nearest; audit unmatched and multiplied rows afterward.
  8. Output contract — use a new output path, preserve a stable feature ID, document schema/CRS/encoding, reopen the artifact, and compare counts/types.

CRS and antimeridian rules

GeoPandas stores CRS as pyproj.CRS. Coordinate arrays use traditional GIS (x, y) order, while authority definitions can advertise latitude-first axes. Use Transformer(..., always_xy=True) for explicit coordinate-array pipelines, and record that choice.

to_crs() transforms vertices and assumes each segment is straight in the source CRS; it does not transform geodesic arcs. Geometries crossing ±180° or a projection boundary can be badly wrapped. Detect crossings, split/unwrap and densify in a documented geographic representation, transform parts, then validate. Do not use Web Mercator as a general measurement CRS.

crs = gdf.crs  # a pyproj.CRS when present
if crs is None or crs.is_geographic:
    raise ValueError("Choose a justified projected CRS before planar measurement")

unit_names = [axis.unit_name for axis in crs.axis_info]
areas = gdf.geometry.area  # square CRS units, not automatically square metres

See CRS management.

Core API decisions

Data structures

  • A GeoDataFrame can hold multiple geometry columns, each with CRS metadata, but only active_geometry_name drives frame-level spatial operations.
  • Binary GeoSeries methods are row-wise and align by index by default. Use align=False only when positional pairing is explicitly intended and lengths and order were verified.
  • Duplicate column names and duplicate feature IDs are ambiguous; reject or resolve them before joins and exports.

See data structures.

Geometry validity, precision, and union

Use is_valid and redacted is_valid_reason() categories before make_valid(method="linework"|"structure", keep_collapsed=...). Repair can change geometry type or dimension; retain the original and compare counts, area, types, empties, and collapsed parts.

set_precision(grid_size, mode=...) uses CRS units and may remove duplicate vertices or collapse features. union_all(method="unary", grid_size=...) is the robust default. Use coverage only after is_valid_coverage() proves non-overlap and edge matching; use disjoint_subset with Shapely >=2.1 when its partitioning assumption is useful.

See geometric operations.

Joins, overlay, clip, and dissolve

  • sjoin predicates are directional: left.within(right) is not left.contains(right). intersects includes boundary contact; contains excludes boundary-only points, while covers includes boundary points.
  • predicate="dwithin" requires distance; scalar or per-left-row distances are in CRS units. sjoin_nearest returns all equidistant nearest matches and does not implement a k= parameter.
  • overlay(..., make_valid=True) repairs invalid input but can change types; keep_geom_type=None drops other types with a warning. Precision mismatch can create slivers; quantify them rather than silently deleting them.
  • clip dissolves the mask. Rectangle clipping is fast but possibly dirty and may omit a line collapsed to a point; validate its output.
  • dissolve combines groupby.agg with union_all; choose explicit attribute aggregations and audit null group keys.

See spatial analysis.

I/O, Arrow, and PostGIS

GeoPandas 1.x defaults to pyogrio. Driver availability and semantics come from the installed GDAL, not GeoPandas alone. Prefer local GeoPackage for general interchange and WKB GeoParquet for columnar interoperability.

GeoParquet defaults to stable schema 1.0.0. Native GeoArrow encodings and bbox covering require schema 1.1.0 and remain less interoperable. A missing GeoParquet crs key means OGC:CRS84; explicit crs: null means unknown—do not conflate them. Reopen and validate every export.

Use parameterized SQL and a SQLAlchemy Engine/Connection for PostGIS. if_exists="replace" is destructive; default to "fail" and use a transaction.

See data I/O.

Migration checklist

For code moving from GeoPandas 0.14 or earlier:

  • GeoPandas 1.0 supports Shapely >=2 only; PyGEOS, Shapely <2, and the rtree spatial-index backend were removed.
  • pyogrio replaced Fiona as the installed/default I/O engine. Set engine= explicitly and test schema, empty, datetime, encoding, and append behavior.
  • Replace sjoin(op=...) with predicate=, sindex.query_bulk() with sindex.query(), unary_union with union_all(), and GeometryArray.data with to_numpy()/np.asarray.
  • Replace read_file(include_fields=...|ignore_fields=...) with columns=. Use schema_version=, not the removed GeoParquet version= compatibility.
  • Do not use removed geopandas.datasets, internal geopandas.io.* entry points, plot axes/colormap, or set-operation operators.
  • explode() now defaults index_parts=False; a named Series passed to set_geometry() supplies the new active-column name; a named right index can replace index_right in sjoin output.
  • Do not assign .crs to override metadata or rely on deprecated set_geometry(drop=...); use explicit set_crs() and rename/drop steps.
  • GeoPandas 1.1 requires Python >=3.10, pandas >=2.0, NumPy >=1.24, and pyproj

    =3.5. Version 1.1.2 fixed SQL injection through a PostGIS geometry-column name; the pinned 1.1.4 includes that fix.

Plotting and exploration

Maps are analytical outputs: label units, classification method, missing data, normalization denominator, and date. explore() can expose every attribute in tooltips/popups and contact tile/CDN servers; generalize first and use tiles=None, tooltip=False, and popup=False for a local draft.

See visualization.

Bundled local CLIs

All helpers are deterministic, reject network/archive paths, bound input bytes and feature counts, keep imports lazy so --help is dependency-free, and emit JSON without coordinates or record identifiers.

CLI Purpose
scripts/vector_inventory.py Redacted local vector/GeoParquet technical inventory
scripts/crs_reprojection_plan.py CRS units, axes, candidate transform and antimeridian plan
scripts/geometry_validity_report.py Dry-run validity audit; optional repair to a new GeoPackage
scripts/spatial_join_audit.py Predicate semantics, duplicate IDs and join cardinality
scripts/export_plan.py Non-executing vector/GeoParquet export contract
scripts/sensitive_coordinates_checklist.py Privacy/generalization release gate
python skills/geopandas/scripts/vector_inventory.py --help
python skills/geopandas/scripts/crs_reprojection_plan.py \
  --source-crs EPSG:4326 --target-crs EPSG:32631
python skills/geopandas/scripts/geometry_validity_report.py data.gpkg
python skills/geopandas/scripts/spatial_join_audit.py points.gpkg zones.gpkg \
  --predicate within --left-id point_id --right-id zone_id
python skills/geopandas/scripts/export_plan.py data.gpkg result.parquet \
  --format geoparquet --schema-version 1.0.0 \
  --stable-id-column feature_id --id-unique-verified
python skills/geopandas/scripts/sensitive_coordinates_checklist.py \
  --public-output --precise-points --contains-addresses

Reference index

Sources (verified 2026-07-23)

04 同仓库更多 Skills

mrsonord2240
mrsonord2240/openscience-specialists

bio-workflows-metabolomics-pipeline

Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics/isotope-tracing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-xcms-preprocessing

Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-statistical-analysis

Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-pathway-mapping

Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-normalization-qc

Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-msdial-preprocessing

Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA/DIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.

★ 2