Spatial Dashboard Streamlit · Panel · Production
Data Reference

GeoDataFrame Schema Reference

A GeoDataFrame is a pandas DataFrame with one or more geometry columns, exactly one of which is “active”, plus a .crs attribute describing how its coordinates map to the Earth. That extra structure is what lets a spatial dashboard reproject, filter by bounding box, and render a map — but it is also fragile. A careless merge silently drops the active-geometry pointer, a read_csv round-trip reduces every polygon to a string, and a wide default dtype turns a 400,000-row point layer into a gigabyte of resident memory. Schema discipline is what keeps a Streamlit or Panel dashboard fast and correct as data flows in from uploads, PostGIS, and Parquet caches.

This page is a working reference for the anatomy of a GeoDataFrame, the per-row memory cost of each column dtype, the full set of geometry types, and canonical schemas for the layer types most dashboards actually render. It then walks a five-step workflow to define, validate, and enforce a schema, covers categorical and pyarrow-backed optimisations, and lists the error messages you will hit when a schema breaks. It sits under Spatial Data Reference alongside the CRS & Coordinate Systems Reference, and the memory numbers below feed directly into Memory Limit Management.

Anatomy of a GeoDataFrame

Four pieces of state define a GeoDataFrame and every schema bug traces back to one of them: the index, the ordinary attribute columns, the geometry column(s), and the metadata that names the active geometry and holds the CRS.

Where a GeoDataFrame's bytes actually liveBar lengths encode bytes per row inside the frame's own memory blocks. A RangeIndex costs nothing because it is virtual. An int32 attribute costs four bytes per row and a float32 costs four; a category column costs one byte per row for its codes plus one shared dictionary. The geometry column costs only an eight-byte pointer per row. A dashed arrow leaves the geometry bar for a separate GEOS arena outside the frame, drawn with three geometries of increasing size — a point of about thirty-two bytes, a fifty-vertex line of roughly nine hundred bytes, and a five-hundred-vertex polygon of about eight kilobytes — showing that geometry cost scales with vertex count, not row count.INSIDE THE FRAME'S BLOCKS — BYTES PER ROWindex — RangeIndex0 B — start/stop/step onlypoi_id — int324 Bcategory — category1 B code + one shared dictionaryrating — float324 Bgeometry — active8 B — a pointer, not a shapeevery pointer dereferences out herememory_usage(deep=True) walks the arena.The default sums only the blocks above, so a500-vertex polygon reports as 8 bytes.GEOS arena — outside the framePoint≈ 32 BLineString(50)≈ 0.9 KBPolygon(500)≈ 8 KB
  • The index. By default a RangeIndex (virtual, ~0 bytes). A materialised int64 index costs 8 bytes/row; an object index of string keys costs far more and is a common, invisible source of bloat.
  • Attribute columns. Ordinary pandas columns. Their dtype is where almost all of the controllable memory lives, and where the table below applies.
  • The geometry column(s). A GeoSeries of shapely objects. A frame may hold several (e.g. geometry plus a centroid column), but only one is active — the one spatial methods and plots use by default.
  • Metadata. Two attributes: _geometry_column_name (which column is active) and .crs (a pyproj.CRS). Neither survives a merge, a pd.concat on mismatched frames, or a CSV round-trip, which is why so many schema bugs surface as “no active geometry” or “CRS is None”.

Column dtype and per-row memory reference

This is the core table: pick the narrowest dtype that preserves the values you actually need. Byte costs are per row for the pandas storage block; object and category costs depend on cardinality and string length, so the figures are typical values for a dashboard-sized frame.

Column roleRecommended dtypeBytes/rowNotes
Row identifier (< 2.1 B)int324Halves the int64 default; fine for feature IDs below ~2.1 billion
Row identifier (large / global)int648Needed for OSM node IDs and Snowflake-style keys
Nullable integerInt32 (pyarrow or pandas)4–5Use when the column has genuine missing values; avoids float coercion
Continuous metricfloat324Halves float64; ~7 significant digits — fine for ratings, populations
High-precision metricfloat648Keep for money, cumulative sums, anything needing 15 digits
Low-cardinality labelcategory~1–2 + dictPOI type, admin level, status — huge win when values repeat
Free text / high-cardinalitystring[pyarrow]~4 + charsNames, addresses; pyarrow strings avoid per-object Python overhead
Legacy textobject~50+Default for strings; boxed Python str per cell — avoid at scale
Boolean flagbool1Use boolean (nullable) only if missing values are meaningful
Timestampdatetime64[ns]8For GPS tracks and time sliders; store UTC, localise at render
H3 cell indexuint64 or category8 / ~2uint64 for math on the index, category if hexbins repeat across rows
Active geometrygeometry~8 + GEOSColumn reports the pointer; true cost is vertex-driven and out-of-band

The single highest-leverage change on most frames is turning repeated-string columns into category and downcasting int64/float64 to 32-bit — the full procedure lives in choosing column dtypes to reduce GeoDataFrame memory.

Geometry types and nullability

The active geometry column should hold a single geometry type. Mixed types (some Polygon, some MultiPolygon) are legal in shapely but break many renderers and every strict schema check. Promote to the Multi* variant when in doubt.

Geometry typeTypical dashboard useVerticesRenderer notes
PointPOI markers, sensor locations, geocoded addresses1Cheapest; cluster at high counts
LineStringGPS tracks, routes, network edges2–NSimplify before rendering long tracks
PolygonAdmin boundaries, parcels, catchmentsring(s)Holes stored as interior rings
MultiPointGrouped observations under one feature IDNRare; usually flatten to Point rows
MultiLineStringMulti-segment routes, rivers with branchesNCommon output of network splits
MultiPolygonCountries with islands, multi-part parcelsNPromote mixed Polygon/MultiPolygon layers to this
GeometryCollectionMixed outputs of overlay/clip opsNAvoid persisting; explode or filter before storing

Nullability matters: geopandas allows a missing geometry (None) and an empty geometry (POLYGON EMPTY), and they behave differently. gdf.geometry.isna() catches None; gdf.geometry.is_empty catches the empty case. A production schema should forbid both in the active geometry column unless the dashboard explicitly handles “no location” rows. Attribute columns are a separate question: a rating may legitimately be missing, but a plain float32 column represents that as NaN, which silently coerces integer columns to float. When missing values are meaningful, reach for the nullable Int32/Float32 dtypes so a null stays a null and the integer type survives.

The active-geometry rule also governs derived columns. Computing gdf["centroid"] = gdf.geometry.centroid adds a second geometry column; it does not change which one is active. Plotting or exporting still uses the original geometry column until you call set_geometry("centroid"). Keeping one column canonical — and treating extra geometry columns as scratch — avoids a whole class of “the map rendered the wrong shapes” bugs.

Canonical schemas for common dashboard layers

These are the schemas to reach for when you design a new layer. They balance memory against the attributes a map actually needs.

LayerColumns → dtypeGeometryCRS
Points of interestpoi_id:int32, name:string[pyarrow], category:category, rating:float32PointEPSG:4326
Choropleth polygonsarea_id:int32, name:string[pyarrow], metric:float32, pop:int32MultiPolygonEPSG:4326 (display), EPSG:3857 (tiles)
GPS trackstrack_id:int32, ts:datetime64[ns], speed:float32LineStringEPSG:4326
H3 hexbinsh3:uint64, resolution:int8, count:int32, density:float32PolygonEPSG:4326

Choropleth work usually renders in Web Mercator; the reprojection details live in the CRS & Coordinate Systems Reference. Point and polygon layers are almost always shipped to the browser as GeoJSON in EPSG:4326 — see converting shapely geometries to GeoJSON for web maps.

Prerequisites

  • Python 3.10+ with geopandas>=0.14, shapely>=2.0, and pandas>=2.1 (pyarrow-backed dtypes are stable from 2.1).
  • pyarrow>=14 for string[pyarrow] columns and Parquet I/O.
  • pandera>=0.18 (optional) for declarative schema validation; the manual-assertion path below needs no extra dependency.
  • Familiarity with EPSG codes and the CRS attribute, covered in the CRS & Coordinate Systems Reference.
bash
pip install "geopandas>=0.14" "shapely>=2.0" "pandas>=2.1" "pyarrow>=14" pandera

Core implementation workflow

Step 1 — Declare the target schema

Write the schema as data before you touch a file. A dictionary is enough and doubles as documentation.

python
TARGET_SCHEMA = {
    "poi_id":   "int32",
    "name":     "string[pyarrow]",
    "category": "category",
    "rating":   "float32",
}
TARGET_GEOM_TYPE = "Point"
TARGET_CRS = "EPSG:4326"

Step 2 — Coerce columns to their declared dtypes

Load, then cast. Casting on load is what stops a read_csv or a PostGIS numeric from silently arriving as object or float64.

python
import geopandas as gpd

def coerce_dtypes(gdf: gpd.GeoDataFrame, schema: dict) -> gpd.GeoDataFrame:
    """Cast each attribute column to its declared dtype; leave geometry untouched."""
    for column, dtype in schema.items():
        if column not in gdf.columns:
            raise KeyError(f"Missing required column: {column!r}")
        gdf[column] = gdf[column].astype(dtype)
    return gdf

raw = gpd.read_file("pois.geojson")          # arrives as int64/object/float64
gdf = coerce_dtypes(raw, TARGET_SCHEMA)

Step 3 — Set the active geometry and CRS

After any reshape you must re-assert which column is active and what its CRS is. set_geometry fixes the active-geometry pointer; set_crs attaches the CRS without reprojecting (use to_crs when you actually want to transform coordinates).

python
gdf = gdf.set_geometry("geometry")

if gdf.crs is None:
    gdf = gdf.set_crs(TARGET_CRS)            # label only — no coordinate change
elif gdf.crs.to_epsg() != 4326:
    gdf = gdf.to_crs(TARGET_CRS)             # actual reprojection
The same violation, caught at four different distancesA column arrives as a string where the schema declares a float. Caught at the ingestion boundary, the assertion names the column and the file, and the fix takes seconds. Caught in the load path, it surfaces as a comparison that silently returns nothing, so an analyst reports a missing region and somebody spends an afternoon reading filter code. Caught at render, it becomes a chart with a category that should not exist, which usually gets explained away as a data quality issue in the source. Caught in a published report, the number was wrong and has already been used. The cost curve is steep and its shape is the argument for the assertion: the check itself is worth almost nothing, and its value is entirely in how far left on this axis it moves the discovery.ONE WRONG DTYPE — COST BY WHERE IT IS CAUGHTthe assertion names the column and the file — secondsa comparison returns nothing — an afternoon reading filter codea chart shows a category that cannot exist — blamed on the sourcethe number was wrong, and somebody has already acted on itingestionload pathrenderpublished reportThe check costs almost nothing to write and nothing to run. Its entire value is how far left along this axis it moves themoment of discovery — which is why it belongs at the boundary rather than wherever the bug happened to surface. ### Step 4 — Validate with pandera or manual assertions

The manual path needs no dependency and covers the four failure modes that matter: wrong dtype, mixed geometry, null geometry, wrong CRS.

python
def validate_schema(gdf: gpd.GeoDataFrame, schema: dict,
                    geom_type: str, crs: str) -> gpd.GeoDataFrame:
    for column, dtype in schema.items():
        actual = str(gdf[column].dtype)
        assert actual == dtype, f"{column}: expected {dtype}, got {actual}"

    assert gdf.geometry.notna().all(), "Active geometry contains null rows"
    assert not gdf.geometry.is_empty.any(), "Active geometry contains empty rows"

    kinds = set(gdf.geom_type.unique())
    assert kinds == {geom_type}, f"Mixed geometry types: {kinds}"

    assert gdf.crs is not None and gdf.crs.to_epsg() == int(crs.split(":")[1]), \
        f"CRS mismatch: {gdf.crs}"
    return gdf

gdf = validate_schema(gdf, TARGET_SCHEMA, TARGET_GEOM_TYPE, TARGET_CRS)

The equivalent with pandera reads as a declarative contract and produces richer error reports:

python
import pandera.pandas as pa
from pandera.typing.geopandas import GeoSeries

class PoiSchema(pa.DataFrameModel):
    poi_id: int = pa.Field(ge=0)
    name: str
    category: str = pa.Field(isin=["cafe", "park", "shop", "museum"])
    rating: float = pa.Field(in_range={"min_value": 0.0, "max_value": 5.0})
    geometry: GeoSeries

    class Config:
        coerce = True

validated = PoiSchema.validate(gdf)

Step 5 — Enforce the schema at every ingestion boundary

Wrap validation around every entry point — file upload, PostGIS read, cached Parquet — so a bad frame fails at the door rather than three widgets later.

python
import streamlit as st

@st.cache_data(ttl=3600, show_spinner="Validating layer…")
def load_poi_layer(path: str) -> gpd.GeoDataFrame:
    gdf = gpd.read_file(path)
    gdf = coerce_dtypes(gdf, TARGET_SCHEMA)
    gdf = gdf.set_geometry("geometry")
    if gdf.crs is None:
        gdf = gdf.set_crs(TARGET_CRS)
    return validate_schema(gdf, TARGET_SCHEMA, TARGET_GEOM_TYPE, TARGET_CRS)

Advanced patterns

Categorical encoding for repeated labels

When a string column has few distinct values relative to its length — a POI category, an admin level, a status — category replaces per-row string storage with a small integer code plus a one-time dictionary.

python
# 400,000 POIs, 12 distinct categories
gdf["category"] = gdf["category"].astype("category")
# object column ~24 MB  ->  category ~0.4 MB (int8 codes + tiny dict)

Do not apply this to a name column: high cardinality means the dictionary approaches one entry per row and the code array is pure overhead.

Three ways to hold the same 400,000 region namesThe same column of region names is drawn three ways. As an object dtype it is an array of pointers, each addressing a separate Python string object elsewhere on the heap with its own header — the storage is scattered, each value costs about sixty bytes of overhead before its characters, and iterating touches memory all over the process. As a category it becomes an array of small integer codes plus one dictionary holding each distinct name once, so four hundred thousand rows drawn from forty distinct regions cost four hundred thousand single bytes plus forty strings. As a pyarrow-backed string it becomes one contiguous byte buffer with an offsets array, so the characters sit together and a scan is sequential. The choice is not purely about size: the categorical form is smallest when the cardinality is low, and the Arrow form stays predictable when it is not.400,000 REGION NAMES, 40 DISTINCT — THREE LAYOUTSobject dtype — pointers into the heapone Python string object per row, scattered≈ 60 bytes of object header before a single charactera scan touches memory all over the processcategory — codes plus one dictionary40 names, once each400,000 single bytes + 40 stringssmallest by far — while the cardinality stays lowpyarrow-backed — contiguous bytes and offsetsone byte bufferoffsetsthe characters sit together; a scan is sequentialpredictable when the cardinality is not lowCardinality decides between the last two — a column of unique identifiers gains nothing from a dictionary. ### pyarrow-backed strings

For genuinely high-cardinality text, string[pyarrow] stores values in a contiguous Arrow buffer instead of boxed Python objects, cutting both memory and serialization time.

python
gdf["name"] = gdf["name"].astype("string[pyarrow]")
gdf["address"] = gdf["address"].astype("string[pyarrow]")

Arrow-backed columns also round-trip through to_parquet without conversion, which makes them the right choice for cached layers.

Downcasting numerics

Let pandas pick the narrowest safe integer/float dtype rather than guessing.

python
import pandas as pd

gdf["pop"] = pd.to_numeric(gdf["pop"], downcast="integer")     # int64 -> int32/int16
gdf["metric"] = pd.to_numeric(gdf["metric"], downcast="float") # float64 -> float32

WKB storage for cache payloads

When a frame is a cache artefact rather than a live working set, replace live shapely objects with Well-Known Binary. WKB is compact, version-stable across shapely releases, and stores cleanly in Redis or Parquet.

python
# Serialize geometry to WKB bytes for a Redis/Parquet cache
gdf["geom_wkb"] = gdf.geometry.to_wkb()
plain = gdf.drop(columns="geometry")          # now an ordinary DataFrame

# Rehydrate only when spatial operations are needed
from geopandas import GeoSeries
geom = GeoSeries.from_wkb(plain["geom_wkb"], crs="EPSG:4326")
restored = gpd.GeoDataFrame(plain.drop(columns="geom_wkb"), geometry=geom)

This is the storage form that keeps cached GeoDataFrames small under the ceilings described in Memory Limit Management.

Recovering a schema from different sources

The dtype a column arrives with depends entirely on where it came from, so schema enforcement must adapt to the source:

python
# GeoJSON / GeoPackage via read_file — geometry and CRS survive,
# but integers arrive as int64 and strings as object.
gdf = gpd.read_file("layer.gpkg")

# PostGIS via read_postgis — geometry and CRS come from the geometry column's
# SRID; numeric precision follows the SQL column type.
from sqlalchemy import create_engine, text
engine = create_engine("postgresql+psycopg2://user:pass@db:5432/gis")
with engine.connect() as conn:
    gdf = gpd.read_postgis(text("SELECT * FROM pois"), conn, geom_col="geom")

# CSV / Parquet with a WKT or WKB geometry column — geometry is a *string*
# until you rebuild it, and the CSV path loses the CRS entirely.
import pandas as pd
df = pd.read_csv("pois.csv")
gdf = gpd.GeoDataFrame(
    df, geometry=gpd.GeoSeries.from_wkt(df["geometry_wkt"]), crs="EPSG:4326"
)

The lesson is that only read_file and read_postgis restore geometry and CRS automatically; every tabular round-trip (CSV, and CSV-backed uploads) drops the CRS and demands an explicit set_crs. Route each source through the same coerce_dtypes + validate_schema pair from the workflow below so the frame is identical downstream regardless of origin.

Schema-stable Parquet caching

GeoParquet is the one on-disk format that preserves the full schema — dtypes, geometry type, and CRS — byte-for-byte across reloads. Writing a validated frame to Parquet and reading it back yields an identical schema without re-coercion, which is why it is the right cache and interchange format:

python
gdf.to_parquet("pois.parquet")          # embeds CRS + dtypes in metadata
restored = gpd.read_parquet("pois.parquet")
assert str(restored["category"].dtype) == "category"
assert restored.crs.to_epsg() == 4326

Verification and testing

Confirm both the schema and the memory profile after loading.

python
gdf = load_poi_layer("pois.geojson")

# Schema assertions
assert gdf.geometry.name == "geometry"
assert set(gdf.geom_type.unique()) == {"Point"}
assert gdf.crs.to_epsg() == 4326
assert str(gdf["category"].dtype) == "category"

# Memory profile — deep=True walks object/geometry blocks
usage = gdf.memory_usage(deep=True)
print(usage)
total_mb = usage.sum() / 1e6
print(f"Total: {total_mb:.1f} MB across {len(gdf):,} rows")
assert total_mb < 60, "Layer larger than expected — check for object dtypes"

memory_usage(deep=True) is the one measurement that catches a stray object column; a wide layer that “should” be small almost always has one.

Troubleshooting

AttributeError: 'DataFrame' object has no attribute 'crs' : A pandas operation (merge, groupby().apply, pd.concat) returned a plain DataFrame. Re-wrap: gdf = gpd.GeoDataFrame(df, geometry="geometry", crs="EPSG:4326"). The crs argument is required because the metadata was lost in the operation.

ValueError: Cannot set a GeoDataFrame without a geometry (or You are calling a geospatial method on the GeoDataFrame, but the active geometry column ... is not present) : No column is registered as active. This follows a rename or a column selection that dropped geometry. Fix with gdf = gdf.set_geometry("geometry"), and confirm the column actually exists first.

Mixed geometry types: {'Polygon', 'MultiPolygon'} (raised by the validation in Step 4) : The source mixes single and multi parts. Promote everything: from shapely.geometry import MultiPolygon; gdf["geometry"] = [g if g.geom_type == "MultiPolygon" else MultiPolygon([g]) for g in gdf.geometry].

CRS is None after read_file or read_postgis : The source had no CRS metadata. If you know the coordinates are already lon/lat, label them with gdf.set_crs("EPSG:4326"). Never use to_crs here — it would reproject from an unknown source and scramble coordinates.

Memory balloons after a join : The join reintroduced an object string index or an int64 key. Run gdf.memory_usage(deep=True) to find the block, then re-apply category/int32/string[pyarrow] casts from the dtype table above.

TypeError: Cannot interpret 'string[pyarrow]' as a data type from a third-party plotting or analysis call : Some libraries still expect NumPy-backed columns. Cast the offending attribute column back at the boundary with gdf["name"] = gdf["name"].astype("object") (or .astype("float64") for numerics) just before the call; keep the Arrow dtype everywhere else.

Integer column silently became float64 : A missing value (NaN) was introduced — usually by a left join that did not match every row. NaN is a float, so pandas promoted the whole column. Switch to the nullable Int32 dtype, which represents missing values as <NA> without abandoning the integer width.

Performance considerations

Profile before optimising. memory_usage(deep=True) is authoritative for attribute columns; geometry memory is vertex-driven, so simplify with gdf.geometry.simplify(0.0001, preserve_topology=True) for display-only layers rather than chasing dtype savings on the geometry column.

Schema stability beats micro-tuning. A frame whose dtypes are locked and validated at ingestion caches deterministically, because to_parquet output is byte-stable — which is exactly what deterministic query result caching needs for reliable cache keys.

Index dtype is invisible bloat. A materialised object index of string keys can outweigh every other column. Prefer a RangeIndex or an int32 index and set string keys as a normal category column instead.

Validate once, at ingestion — not per render. Schema checks that walk every geometry are not free; running validate_schema on each Streamlit rerun re-scans the whole frame. Do it inside the cached loader (Step 5) so the cost is paid once per TTL, and let downstream widgets trust the frame. This mirrors the session isolation principle: expensive, deterministic work belongs behind the cache boundary, not in the interaction path.

Back to Spatial Data Reference

Related