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

Document ID: CNL-FN-2026-035
Version: 0.1
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). The AI 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

A conversation originating from the receipt of shapefile boundary data for the Steele-Bernand 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, and outlines the reciprocal relationship between point samples and area analyses. No implementation is proposed; this note preserves the thinking for future development.

1. Origin

During a field expedition to Borrego Springs, California (March 2026), the author received a shapefile set delineating the boundary of the Steele-Bernand Anza-Borrego Desert Research Center. 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. 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.

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 likely 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-Bernand 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 vast 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. Remarkably simple API.
• Shapely — Geometry operations (intersection, buffer, union) in Python.
• GeoPandas — Spatial DataFrames combining Pandas with Shapely geometries.
• 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. It has 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) throughout 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. 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. Open Questions

1. Instrument identity: Is the Spatial Analyst a standalone Lab (Lab 06), or a mode/capability that augments existing instruments when a boundary is active?
2. Boundary sources: User-uploaded shapefiles converted server-side? Boundaries drawn in the browser? Hosted feature layers from ESRI? 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 is likely: cross-instrument synthesis with the full YEA suite. That must remain the value proposition.

8. Disposition

This note is filed for reference. No implementation work is proposed at this time. The Spatial Analyst concept will be revisited after the current instrument development priorities (Site Finder refinement, Atmosphere panel, eBird/BirdWeather integration) are completed. The Steele-Bernand shapefile provides a concrete test case whenever development begins.

Document History