Toward a Spatial Analyst: Points, Areas, and the Worm’s Eye View

Document ID: CNL-FN-2026-035
Version: 0.9
Date: March 12, 2026
Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This field note was developed with assistance from Claude (Anthropic, Opus 4.6) and Perplexity (GPT-5.1). The AIs contributed to technical library survey, architectural analysis, and manuscript drafting based on a working conversation initiated by the author during a field expedition to Anza-Borrego Desert State Park. The author takes full responsibility for the content, accuracy, and conclusions.

Abstract

The receipt of shapefile boundary data for the Steele/Burnand Anza-Borrego Desert Research Center prompted an architectural inquiry into how the YEA Labs instrument suite might formalize spatial analysis over areas, complementing the existing point-based ecological address paradigm. This note documents the conceptual framing, identifies a novel “worm’s eye” sampling methodology distinct from conventional top-down GIS zonal statistics, surveys the relevant technical libraries, outlines the reciprocal relationship between point samples and area analyses, and proposes a minimal implementation slice suitable for a proof-of-concept session.

1. Origin

During a field expedition to Borrego Springs, California (March 2026), the author received a shapefile set delineating the boundary of the Steele/Burnand Anza-Borrego Desert Research Center, an approximately 88-acre UC Natural Reserve System facility adjacent to Anza-Borrego Desert State Park. The immediate question — how would YEA Labs handle this data? — revealed that the Macroscope lacks a formal instrument for spatial analysis over defined areas, even though area-based queries are already operationally present in the system.

2. The Point-Area Tension in YEA

YEA.earth was conceived as a point-sampling system. A user drops a coordinate, and the instrument suite — Climate Analyst, Habitat Analyst, Biodiversity Analyst, Panorama Analyst — returns everything knowable about that location. The ecological address is fundamentally a point.

However, two existing capabilities already operate on areas:

• Curated Places are defined research areas with spatial extent, not points.
• The Biodiversity Analyst queries iNaturalist observations within a map extent bounding box — an area query, not a point sample.

Planned integrations (eBird, BirdWeather) will deepen area-based querying; both APIs are typically accessed by spatial extent or hotspot polygon rather than single coordinates. The spatial paradigm is already latent in the system. The question is whether to formalize it as an instrument and, if so, what conceptual model governs it.

3. Two Epistemologies of Spatial Analysis

3.1 Bird’s Eye View (Conventional GIS)

Standard GIS operates top-down. Given a polygon boundary, the analyst clips raster layers to the polygon and computes zonal statistics — land-cover composition, mean elevation, precipitation totals. The data exists as continuous spatial fields; the polygon defines the region of interest. The analyst hovers above and summarizes.

This approach is fast, statistically complete (it uses all pixels), and methodologically clean for variables that exist in raster form — DEMs, climate normals, land-cover products such as NLCD, LANDFIRE EVT, EarthEnv consensus land cover, and GLAD land-use change grids.

3.2 Worm’s Eye View (Ecological Address Grid)

An alternative approach distributes a grid of YEA ecological addresses across the landscape within a boundary. Each grid node is a full instrument reading — climate history, habitat classification, biodiversity observations, atmospheric conditions. The landscape understanding emerges from the accumulation of ground-level profiles rather than from aerial summarization.

This mirrors how field ecology actually works: transects, plot grids, systematic sampling across a study area. Knowledge is built from within the system, not imposed from above.

3.3 Comparative Assessment

Synthesis: The two approaches are complementary, not competing. Raster zonal statistics serve continuous spatial fields that already exist in raster form. The worm’s eye grid serves heterogeneous API sources — occurrence records, point measurements, observational data — that have no raster equivalent. A Spatial Analyst needs both, applied to the appropriate data types.

4. The Reciprocal Feedback Loop

The most architecturally significant insight is that point samples and area analyses are not parallel programs but a reciprocal system.

Area → Point: If the Spatial Analyst has characterized a curated place — landscape composition, heterogeneity index, species richness gradient, habitat transition zones — that context becomes available to any point sampled within the boundary. A YEA.earth data card for a coordinate inside the Steele/Burnand boundary gains a “landscape context” dimension it could not generate from its own coordinate alone. A point in creosote scrub reads differently when the system knows it sits at the margin of an alluvial fan where three habitat types converge within 500 meters versus in the interior of a homogeneous basin.

Point → Area: Every YEA.earth point sample taken inside a curated place boundary contributes to the spatial engine’s characterization of that area. The two programs — point sampling and area analysis — form a reciprocal system. Points inform areas; areas contextualize points.

This feedback loop is the architectural argument for building the Spatial Analyst as an integrated instrument rather than a standalone GIS tool. The value is not in replicating what QGIS already does on the desktop, but in connecting spatial analysis to the full instrument suite bidirectionally.

5. Technical Library Survey

The following libraries and tools are compatible with the existing LAMP stack (Apache, PHP 8.3+, MySQL 8.4+, vanilla JavaScript ES modules) without introducing PostGIS or ArcGIS.com dependencies.

5.1 JavaScript / Browser

• GeoTIFF.js — Reads Cloud Optimized GeoTIFFs (COGs) in the browser via HTTP range requests. Enables querying raster pixels over a study area without downloading full files. Pairs with the existing Mapbox GL rendering pipeline.
• Turf.js — Client-side GeoJSON spatial operations: point-in-polygon, area calculation, bounding box, grid generation. Natural engine for constructing worm’s eye sampling grids.
• Mapbox GL JS — Already in use across YEA Labs. Natively supports raster tile sources, which the Atmosphere panel specifications (CNL-SP-2026-028) are already exploiting for IMERG precipitation overlays.

5.2 Python / Server-Side

• Rasterio — Reads and writes virtually any raster format, built on GDAL. The workhorse for server-side raster operations.
• rasterstats — Purpose-built for zonal statistics: accepts a GeoJSON polygon and a raster file path, returns summary statistics via zonal_stats() with support for categorical=True mode for land-cover composition.
• Shapely — Geometry operations (intersection, buffer, union) in Python.
• GeoPandas — Spatial DataFrames combining Pandas with Shapely geometries. Useful for batch operations over multiple polygons.
• GDAL/OGR — Command-line tools for format conversion. A single ogr2ogr command converts shapefiles to GeoJSON.
• pystac / stackstac — STAC (SpatioTemporal Asset Catalog) ecosystem for querying modern Earth observation data catalogs. Worth tracking for future satellite data integration.

5.3 MySQL 8.4 Spatial

MySQL’s spatial extensions provide full ST_ function support: ST_Contains, ST_Intersects, ST_Within, ST_GeomFromGeoJSON, ST_Area, ST_Buffer. Suitable for storing place boundaries in the yea_places table and executing vector queries (point-in-polygon tests, boundary intersection).

Limitation: MySQL spatial is a vector engine with no raster capability. PostGIS (PostgreSQL) would be the gold standard for raster SQL, but this would break the existing stack. The recommended approach is to handle all raster operations in Python/Rasterio and use MySQL exclusively for vector/boundary storage and queries.

5.4 Recommended Architecture Pattern

• Storage: Boundaries as GeoJSON in MySQL spatial columns; raster data as Cloud Optimized GeoTIFF files on disk or remote.
• Server processing: Python/Rasterio for raster zonal statistics, invoked by PHP as background processes.
• API layer: PHP endpoints consuming Python outputs and MySQL spatial query results.
• Browser rendering: Mapbox GL for map display, GeoTIFF.js for client-side raster queries, Turf.js for geometry operations and grid generation.
• Interchange format: Cloud Optimized GeoTIFF (COG) for raster; GeoJSON for vector.

6. Connection to Atmosphere Panel

The Atmosphere panel specifications (CNL-SP-2026-027, CNL-SP-2026-028) are building spatial infrastructure relevant to a future Spatial Analyst, whether or not that was the original design intent. The IMERG precipitation overlay (CNL-SP-2026-028) establishes a pattern for rendering global raster data in Mapbox GL from COG or tile sources. The Sandwalk interface (CNL-SP-2026-027) introduces the satellite crop — a spatial extent centered on a coordinate. These precedents demonstrate that the YEA front-end can handle 2D spatial fields, not only point queries.

7. YEA as Implicit Rasterization Engine

The worm’s eye approach implies a broader architectural principle worth stating explicitly: YEA functions as an implicit rasterization engine. Any point-addressable instrument — climate history, ecoregion taxonomy, biodiversity inventories, bird detections, future sensors — can be sampled over a regular grid of coordinates to produce gridded or zonal products, even when no external raster source exists.

For a given boundary, a regular grid of points is generated inside the polygon (via Turf.js client-side or Shapely server-side). Each point is submitted to the existing YEA instrument stack as a normal ecological address query. The resulting table — rows as grid nodes, columns as instrument outputs — constitutes a derived spatial dataset that can be visualized, summarized, and stored. Over time, some of these grids may themselves be persisted as Cloud Optimized GeoTIFFs, turning YEA-derived fields into first-class raster layers consumable by the same Spatial Analyst machinery that operates on external rasters.

This is not a feature to build immediately. It is a design principle to preserve: the architecture should never foreclose the possibility of gridded sampling across any instrument.

8. Minimal Proof-of-Concept Slice

To validate the architecture without overbuilding, the first implementation should exercise one narrow operation end-to-end:

Given a curated place ID, return a JSON object describing landscape composition from a single categorical raster layer.

8.1 Components

• Vector store: yea_places.geom (MySQL spatial column) holds the curated place boundary as geometry. The Steele/Burnand shapefile is converted to GeoJSON via ogr2ogr and inserted.
• Raster store: One Cloud Optimized GeoTIFF — a LANDFIRE EVT tile or EarthEnv consensus land-cover grid covering the Anza-Borrego region.
• Python worker: A small script accepting a place geometry (as GeoJSON) and a raster path, returning class fractions and pixel counts via rasterstats.zonal_stats() with categorical=True.
• PHP API endpoint: GET /api/spatial/places/{place_id}/landcover with an optional raster parameter; returns JSON with class codes, labels, pixel counts, total area, and fractional composition.
• UI card: A “Landscape Composition” card on the curated place page displaying a bar chart and textual summary.

8.2 Steele/Burnand Test Case

The Steele/Burnand boundary (~88 acres) serves as the proof-of-concept polygon. Using LANDFIRE EVT as the test raster, the expected output would show categorical composition — likely dominated by creosote bush-white bursage desert scrub, with smaller fractions of desert wash woodland and developed area around the former golf course footprint. Actual percentages will be determined by running the real zonal statistics during the lab session; they are not estimated here.

Any point-level YEA ecological address within the boundary could then attach this place-level composition as a data card, realizing the Area → Point half of the reciprocal feedback loop described in Section 4.

8.3 What This Proves

A successful proof of concept demonstrates that the LAMP stack can execute server-side raster analysis against a database-stored vector boundary and return the result through the existing API/UI pattern — without PostGIS, without ArcGIS.com, and without departing from the YEA Labs instrument architecture. Everything more ambitious — the worm’s eye grid, multi-raster queries, the full reciprocal loop — builds on this foundation.

9. Open Questions

1. Instrument identity: Is the Spatial Analyst a standalone Lab (Lab 06), or a mode that augments existing instruments when a boundary is active?
2. Boundary sources: User-uploaded shapefiles converted server-side? Boundaries drawn in the browser? ESRI hosted feature layers? Curated place polygons from the database? All of the above?
3. Grid resolution: Fixed regular grid, or adaptive sampling based on habitat heterogeneity? (Transition zones between alluvial fans and bajada warrant denser sampling than homogeneous creosote flats.)
4. Research session integration: Does a sampling grid constitute a research object in the session system (CNL-TN-2026-030)? The grid-as-session-object is an appealing conceptual fit.
5. Performance: N simultaneous API queries per grid node across M nodes could produce significant load. Caching strategy and rate limiting need consideration.
6. Scope boundary with QGIS: What does the web-based Spatial Analyst do that QGIS on the desktop does not? The answer must be: cross-instrument synthesis with the full YEA suite.

10. Disposition

This note documents the architectural thinking for a Spatial Analyst capability within YEA Labs. The minimal proof-of-concept slice described in Section 8 — a single categorical raster zonal query against the Steele/Burnand boundary — is designated as the entry point for the next available lab session. The broader concepts (worm’s eye grid, reciprocal feedback loop, implicit rasterization engine) are preserved here as design principles to guide subsequent development.

References

• CNL-SP-2026-027: YEA Atmosphere Panel — Sandwalk Interface Specification
• CNL-SP-2026-028: YEA Atmosphere Panel — Global Precipitation Overlay Specification
• CNL-TN-2026-030: YEA Research Session System Architecture

Document History