brycewang-stanford/Auto-Empirical-Research-Skills / skills/17-DAAF-Contribution-Community-daaf/dot-claude/skills/geopandas
geopandas
VerifiedSpatial data: GeoDataFrames, spatial joins, CRS/projections, choropleth/interactive maps, spatial autocorrelation, PySAL. Use for geographic data, spatial files (Shapefile, GeoPackage, GeoParquet), or spatial stats. For charts without GIS use plotly.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.8 KB |
| references/crs-projections.md | markdown | 9.0 KB |
| references/data-io.md | markdown | 8.1 KB |
| references/gotchas.md | markdown | 10.6 KB |
| references/pysal-spatial-stats.md | markdown | 15.8 KB |
| references/quickstart.md | markdown | 7.6 KB |
| references/raster-integration.md | markdown | 9.6 KB |
| references/spatial-operations.md | markdown | 11.0 KB |
| references/visualization.md | markdown | 14.1 KB |
references/crs-projections.md
View on GitHub# CRS and Projections
Coordinate Reference System handling in geopandas — checking, setting, transforming, and choosing projections. Getting the CRS right is a prerequisite for correct spatial operations; getting it wrong produces silently wrong results.
---
## CRS Fundamentals
### Geographic vs Projected CRS
| Property | Geographic CRS | Projected CRS |
|----------|---------------|---------------|
| Coordinates | Longitude/latitude (degrees) | Easting/northing (meters or feet) |
| Earth model | 3D ellipsoid | 2D flat plane |
| Standard example | WGS84 (EPSG:4326) | NAD83 Conus Albers (EPSG:5070) |
| Distance units | Decimal degrees (not constant!) | Meters (constant within valid region) |
| Area calculation | Wrong — 1 degree varies by latitude | Correct (within projection's valid region) |
**The critical rule:** Buffer, area, distance, and centroid operations on a geographic CRS (longitude/latitude) produce wrong or misleading results because one degree of longitude varies from ~111 km at the equator to ~0 km at the poles. Always reproject to an appropriate projected CRS before computing.
---
## Checking CRS
```python
# Check the current CRS
print(gdf.crs)
# Output: EPSG:4326 (or the full WKT2 string)
# Check EPSG code
print(gdf.crs.to_epsg())
# Output: 4326
# Check if geographic (lon/lat) or projected
print(gdf.crs.is_geographic)
# Output: True
print(gdf.crs.is_projected)
# Output: False
# Check the axis units
print(gdf.crs.axis_info)
# Shows units (degree vs metre)
# Detailed CRS information
print(gdf.crs.to_wkt(pretty=True))
```
---
## Setting CRS (Declaring, Not Transforming)
**Setting** a CRS tells geopandas what system the coordinates are already in. No coordinate values change. Use this when data arrives without CRS metadata (common with CSV files containing lat/lon columns).
```python
# Set CRS on creation
gdf = gpd.GeoDataFrame(df, geometry=gpd.points_from_xy(df.lon, df.lat), crs="EPSG:4326")
# Set CRS on existing GeoDataFrame (no CRS currently set)
gdf = gdf.set_crs("EPSG:4326")
# Override an incorrect CRS (use cautiously — you're saying "the existing CRS label is wrong")
gdf = gdf.set_crs("EPSG:4326", allow_override=True)
```
**When to use `set_crs`:** Only when the GeoDataFrame has no CRS (`gdf.crs is None`) or when you know the existing CRS label is incorrect. If the data already has a CRS and you want to change the projection, use `to_crs` instead.
---
## Reprojecting (Transforming Coordinates)
**Reprojecting** recomputes all coordinate values from one CRS to another. Use this when you need a different projection for analysis or visualization.
```python
# Reproject to NAD83 Conus Albers (equal-area, good for US maps)
gdf_albers = gdf.to_crs(epsg=5070)
# Reproject using CRS string
gdf_utm = gdf.to_crs("EPSG:32617")
# Reproject using PROJ string (less common)
gdf_custom = gdf.to_crs("+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=37.5 +lon_0=-96")
# Reproject to match another GeoDataFrame's CRS
gdf_matched = gdf.to_crs(other_gdf.crs)
```
### Setting vs Transforming: The Difference
```python
# WRONG: Using set_crs to "reproject" — coordinates don't change, CRS label changes
# This makes the data plot in the wrong location
gdf_wrong = gdf.set_crs("EPSG:5070") # DON'T DO THIS if gdf is in EPSG:4326
# RIGHT: Using to_crs to reproject — coordinates are recomputed
gdf_right = gdf.to_crs(epsg=5070) # Coordinates change, CRS changes
```
---
## Choosing a Projection
### Decision Guide
```
What does your analysis need?
├─ Area calculations or thematic maps
│ └─ Equal-area projection
│ ├─ Continental US → EPSG:5070 (NAD83 Conus Albers)
│ ├─ Single state → State Plane (equal-area variant) or LAEA
│ ├─ Global → Mollweide or Equal Earth
│ └─ Custom study area → LAEA centered on study centroid
├─ Distance or local-scale analysis (<500 km)
│ └─ UTM zone for study area
│ Use pyproj to find the right zone:
│ from pyproj import CRS
│ CRS.from_authority("EPSG", pyproj.database.query_utm_crs_info(
│ datum_name="WGS 84", area_of_interest=pyproj.aoi.AreaOfInterest(
│ west_lon_degree=-77, south_lat_degree=38,
│ east_lon_degree=-76, north_lat_degree=39))[0].code)
├─ Web map display
│ └─ Web Mercator (EPSG:3857) — display only, never for analysis
├─ Data storage or exchange
│ └─ WGS84 (EPSG:4326)
└─ Unsure
└─ Start with EPSG:5070 for US, UTM for local
```
### Common US Projections
| EPSG | Name | Best For | Units |
|------|------|----------|-------|
| 4326 | WGS84 | Storage, exchange (not analysis) | Degrees |
| 5070 | NAD83 Conus Albers | Continental US thematic maps, area calculations | Meters |
| 3857 | Web Mercator | Web tile display only | Meters (distorted) |
| 32617 | UTM Zone 17N | US East Coast local analysis | Meters |
| 32610 | UTM Zone 10N | US West Coast local analysis | Meters |
| 2163 | US National Atlas (deprecated; prefer 9311) | General US reference maps | Meters |
### State Plane Coordinate Systems
Each US state has one or more State Plane zones optimized for local accuracy. Find the right one:
```python
import pyproj
# List available State Plane CRS for a state
results = pyproj.database.query_crs_info(
auth_name="EPSG",
area_of_interest=pyproj.aoi.AreaOfInterest(
west_lon_degree=-78.0, south_lat_degree=38.0,
east_lon_degree=-75.0, north_lat_degree=40.0
),
crs_types=["PROJECTED_CRS"]
)
# Filter results for "State Plane" in the name
```
### Custom LAEA (Lambert Azimuthal Equal-Area)
For study areas not well-served by standard projections, create a custom equal-area projection centered on your data:
```python
# Center the projection on your study area
centroid = gdf.to_crs(epsg=4326).dissolve().centroid.iloc[0]
custom_crs = f"+proj=laea +lat_0={centroid.y} +lon_0={centroid.x} +datum=WGS84 +units=m"
gdf_custom = gdf.to_crs(custom_crs)
```
---
## CRS Matching Before Spatial Operations
All spatial operations (join, overlay, distance, etc.) require both inputs to be in the same CRS. geopandas raises a `CRSMismatchError` if they differ.
```python
# Check if two GeoDataFrames share the same CRS
if gdf1.crs == gdf2.crs:
result = gpd.sjoin(gdf1, gdf2)
else:
# Reproject one to match the other
gdf2_reprojected = gdf2.to_crs(gdf1.crs)
result = gpd.sjoin(gdf1, gdf2_reprojected)
```
### Best Practice: Reproject Early
```python
# Standard workflow: reproject all inputs to a common CRS at the start
TARGET_CRS = "EPSG:5070"
counties = gpd.read_file("counties.gpkg").to_crs(TARGET_CRS)
schools = gpd.read_file("schools.gpkg").to_crs(TARGET_CRS)
tracts = gpd.read_file("tracts.gpkg").to_crs(TARGET_CRS)
# Now all spatial operations work without CRS concerns
```
---
## pyproj CRS Objects
geopandas uses pyproj for CRS handling. The `pyproj.CRS` object provides rich CRS information:
```python
from pyproj import CRS
# Create from EPSG
crs = CRS.from_epsg(5070)
# Create from PROJ string
crs = CRS.from_proj4("+proj=aea +lat_1=29.5 +lat_2=45.5 +lon_0=-96 +datum=NAD83")
# Create from WKT
crs = CRS.from_wkt(wkt_string)
# Inspect properties
print(crs.name) # NAD83 / Conus Albers
print(crs.is_geographic) # False
print(crs.is_projected) # True
print(crs.axis_info) # Axis names, directions, units
print(crs.area_of_use) # Valid geographic extent
print(crs.to_epsg()) # 5070
# Get UTM zone for a point
from pyproj import database
utm_results = database.query_utm_crs_info(
datum_name="WGS 84",
area_of_interest=pyproj.aoi.AreaOfInterest(
west_lon_degree=-77.1, south_lat_degree=38.8,
east_lon_degree=-76.9, north_lat_degree=39.0
)
)
print(f"EPSG:{utm_results[0].code}") # e.g., EPSG:32618
```
---
## Common CRS Pitfalls
| Pitfall | Symptom | Fix |
|---------|---------|-----|
| Area computed in geographic CRS | Areas in square degrees (tiny numbers) | Reproject to equal-area CRS first |
| Buffer in degrees | Circular buffers become elliptical | Reproject to projected CRS first |
| Distance in degrees | Values like 0.01 instead of 1000 m | Reproject to projected CRS first |
| `set_crs` used instead of `to_crs` | Data plots in wrong hemisphere/location | Use `to_crs` to reproject |
| Web Mercator for analysis | Areas wildly wrong (Greenland = Africa) | Use equal-area projection |
| Missing CRS after pandas operation | `gdf.crs` is None | Re-set CRS: `gdf = gdf.set_crs("EPSG:4326")` |
| Mixed CRS in spatial join | `CRSMismatchError` | Reproject to common CRS |
---
## References and Further Reading
Dorman, M., Graser, A., Nowosad, J., and Lovelace, R. (2025). *Geocomputation with Python*, Chs. 1 and 6: "Geographic data" and "Reprojecting geographic data." https://py.geocompx.org/
Tenkanen, H., Heikinheimo, V., and Whipp, D. (2024). *Introduction to Python for Geographic Data Analysis*, Ch. 5: "Map projections." https://pythongis.org/
pyproj documentation. https://pyproj4.github.io/pyproj/
Battersby, S. (2017). "Map Projections." *The Geographic Information Science & Technology Body of Knowledge*. https://gistbok.ucgis.org/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |