YEA Labs: A Research Instrument Suite for Quantitative Ecological Analysis

Architecture, Implementation, and Future Development

Document ID: CNL-TN-2026-030 Version: 1.0 Date: March 8, 2026 Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This technical note was developed with assistance from Claude (Anthropic, Opus 4.6). The AI contributed to system architecture design, code implementation across PHP/JavaScript/CSS/Python, database schema design, API development, and manuscript drafting. The author takes full responsibility for the content, accuracy, and conclusions.

1. Abstract

YEA Labs is a web-based research instrument suite integrated into the Your Ecological Address (YEA) platform at yea.earth. The system provides five operational instruments for quantitative ecological analysis across a curated network of 1,142 natural areas spanning six continents. Each instrument shares a common place selection system with advanced faceted filtering across geographic, organizational, and ecological dimensions, enabling researchers to navigate between analytical perspectives while maintaining place context. The architecture is built on a LAMP stack with vanilla JavaScript, Chart.js for visualization, Mapbox GL for cartography, and the iNaturalist API for biodiversity data. A batch enrichment pipeline caches non-ephemeral ecological data from eight geospatial APIs, providing instant habitat characterization without live API calls. This note documents the system architecture, the five operational instruments, the data enrichment infrastructure, and the planned development of research session management, cross-instrument pattern analysis, and AI-assisted interpretive synthesis.

2. Introduction

The Macroscope project, initiated at the Canemah Nature Laboratory in Oregon City, Oregon, integrates sensor networks, artificial intelligence, and ecological data visualization into a unified research framework organized around four domains: EARTH (geography, climate, environment), LIFE (biodiversity, taxonomy, ecology), HOME (human-built habitat), and SELF (personal health, work, social). YEA Labs represents the EARTH and LIFE instrument suite within this framework.

The system is designed around the concept of curated places — natural areas that have been enriched with ecological address data from multiple geospatial APIs and indexed for comparative analysis. Unlike traditional GIS workstations that require specialized software and expertise, YEA Labs operates entirely in the web browser, making ecological research tools accessible to field station managers, students, citizen scientists, and professional ecologists.

This note describes the system as implemented through March 8, 2026, including three days of intensive development that produced five operational instruments, a batch enrichment pipeline, a data curation system, and public-facing pages integrated with the YEA site.

3. System Architecture

3.1 Technology Stack

The system runs on a Mac Mini M4 Pro (Galatea) with 1Gb fiber, managed by WebMon. The stack consists of Apache 2, PHP 8.3+ with mysqli, MySQL 8.4+, vanilla JavaScript (ES modules, no build step), and CSS with no preprocessor. Chart.js 4.4.1 provides data visualization. Mapbox GL JS 2.15.0 provides cartographic rendering with native clustering. Pannellum provides 360-degree panoramic viewing. Three.js r128 supports WebGL point cloud rendering for the terrarium viewer.

3.2 Three-Tier Data Architecture

YEA Labs organizes data into three tiers:

Level 1 — Ecological Address APIs. Twenty-one external geospatial data sources, each with defined cache TTLs ranging from 15 minutes (weather) to permanent (geology, ecoregions). Responses cached in the lookup_cache table keyed by 3-decimal coordinate pairs (~111m precision).

Level 2 — Curated Places. 1,142 published natural areas in the yea_places table with geographic coordinates, organizational affiliations (junction table), place type classifications (junction table), continent, country, and ecological override columns for curator-verified corrections.

Level 3 — Instrument Views. Each Lab instrument reads from Level 1 and Level 2 data, presenting it through a specialized analytical lens — climate time series, habitat profiles, biodiversity observations, or panoramic imagery.

3.3 Shared Components

All instruments share a common architecture:

Search API (search_api.php). Serves all published places with ecological context from lookup_cache, organizational affiliations from junction tables, and curated overrides from yea_places. Supports text search, geographic filtering (continent, country), organizational filtering (by ID through junction tables), ecological filtering (biome, Köppen climate zone from cached data), and a panorama availability flag.

Filter Drawer Pattern. A slide-out drawer with six filter dimensions, active filter pills with individual removal, badge count on the filter button, and debounced text search. Implemented identically across all instruments for cognitive consistency.

Cross-Instrument Linking. Each instrument's detail or summary panel includes contextual links to other instruments, passing place slug, coordinates, and name via URL parameters. Receiving instruments auto-select the place on load. Links are conditional — the Panorama Analyst link only appears for places with panorama data.

4. Operational Instruments

4.1 Lab 01: Site Finder

The Site Finder provides advanced search and discovery across the curated place network. The center viewport displays a Mapbox satellite globe with native clustering — green circles with count labels at zoom-out, individual dots at zoom-in. Clicking a cluster zooms to expand it; clicking a point selects the place. The right detail panel shows location, organizational affiliations with roles, ecological context with curated override indicators, and cross-links to all other instruments.

The ecological override system allows curators to correct API-derived classifications. Override columns on yea_places (biome_override, ecoregion_override, climate_zone_override, landcover_override) take precedence over lookup_cache values. When an override exists, both the curated value and the original API value are displayed with provenance. An inline edit form is available to authenticated administrators.

4.2 Lab 02: Climate Analyst

The Climate Analyst provides 34-year historical climate profiles and real-time current conditions for any curated place. The center viewport renders three Chart.js visualizations:

Temperature Envelope. Monthly mean, maximum, and minimum temperatures (1991–2025) as a line chart with filled area for the mean.

Precipitation. Monthly precipitation and snowfall totals as stacked bar charts.

Water Balance. Monthly precipitation minus FAO Penman-Monteith reference evapotranspiration (ET₀), with blue bars for surplus months and red bars for deficit months.

An annual summary strip shows mean temperature, total precipitation, total ET₀, and net water balance.

The right panel displays current conditions using a two-tier weather source strategy: Weather Underground personal weather stations (PWS) are attempted first, iterating up to five nearby stations within 5 miles, validated against an Open-Meteo modeled baseline (±10°F tolerance). If no valid PWS is found, the Open-Meteo model serves as fallback. Source attribution is displayed. A "vs Normal" comparison shows the current temperature's departure from the 34-year monthly mean.

Climate archive data is cached permanently in lookup_cache after first fetch (~588KB per place, ~30 seconds from Open-Meteo Historical API). Subsequent visits are instant.

4.3 Lab 03: Panorama Analyst & Terrarium Designer

The Panorama Analyst navigates 360-degree panoramic imagery across 33 field stations with seasonal and annual switching. The left panel lists stations with circular thumbnail previews; selecting a station shows its photo locations. A timeline bar at the viewport bottom provides chronological navigation across seasons and years. Green dots on timeline markers indicate locations with 3D terrarium data.

The terrarium viewer renders Gaussian splat point cloud reconstructions in four modes: image, points, splat, and wireframe. Controls for point size and wire density are in the left panel. The rendering engines (panorama.js, terrarium.js, webxr.js) were extracted from the ecoSPLAT proof-of-concept viewer and decoupled from its dashboard architecture for reuse across instruments.

4.4 Lab 04: Habitat Analyst

The Habitat Analyst synthesizes seven cached ecological classification layers into a scrollable habitat profile. All data is read from lookup_cache with no live API calls, providing instant rendering. The profile cards include:

The summary panel shows quick facts, coordinates, and a source availability grid with green tags for cached sources and gray tags for missing data.

4.5 Lab 05: Biodiversity Analyst

The Biodiversity Analyst plots iNaturalist species observations on a satellite map for any curated place. The default view shows the Mapbox globe with clustered place markers matching the Site Finder pattern. Selecting a place zooms to its radius and fetches observations with progressive pagination (up to 600 records). Observations are filtered to genus-level or finer identifications and rendered as taxon-colored map markers.

The right taxon sidebar shows observation count, adjustable search radius (1×, 2×, 5× multiplier), taxon group filters with click-to-isolate behavior, and a scrollable species list with common names, binomials, and observation counts. The observation engine (inat.js) supports session caching, lightbox photo viewing, and popup cards with iNaturalist links.

5. Data Enrichment Infrastructure

5.1 Batch Enrichment Pipeline

A Python script (enrich_places.py) iterates through all 1,142 published places and caches non-ephemeral ecological data from eight geospatial APIs. The script parses database and API credentials from the same PHP configuration files used by the web application, constructs API URLs matching the field guide's sources.php patterns, and stores responses in lookup_cache with the same coordinate key format.

The enrichment run completed in approximately 40 minutes for 1,142 places across eight sources, with automatic CONUS detection for US-only sources (EPA Omernik, NLCD, LANDFIRE EVT). Rate limiting (0.3 seconds between requests) prevents API throttling. The script skips already-cached entries by default.

5.2 Country and Continent Data Cleanup

A companion script (fix_countries.py) resolved data quality issues in the country field of yea_places. The original data contained continent names (Europe, Asia, Africa) in the country column for 459 places imported from the ILTER network, duplicates (USA vs. United States), and null values. The script added a continent column, extracted actual country names from cached Mapbox reverse geocode data in lookup_cache, and populated continent from a country-to-continent lookup table. 651 country corrections and 1,098 continent assignments were made.

5.3 Curated Overrides

Seven columns on yea_places support curator-verified corrections to API-derived ecological classifications: biome_override, ecoregion_override, climate_zone_override, landcover_override, override_notes, overridden_by, and overridden_at. NULL values indicate "use the API data from lookup_cache." Populated values take precedence. The override_notes field documents rationale. The search API returns both the effective value and the original API value for provenance, and a has_override flag for UI indication.

6. Database Schema Extensions

YEA Labs operates within the existing ecological_address database, using the lookup_cache table for all cached API responses and the yea_places table (with extensions) for curated place data. New tables include:

yea_lab_instruments. Instrument registry with lab_number, slug, name, description, href, status (planned/development/live), visible flag, and sort_order. Drives both the admin Lab dashboard and the public Labs page.

The existing junction tables yea_place_organizations and yea_place_type_links provide many-to-many relationships that the search API queries through for filter options and per-place organizational/type data.

7. Public Interface

Each instrument has both an admin version (requiring authentication, with curation controls) and a public version (no authentication, read-only). Public pages live in the labs/ directory, load the same JavaScript modules from admin/lab/js/ via relative paths, and set a window.LAB_CONFIG_OVERRIDE object to redirect API paths. A window.LAB_PUBLIC flag suppresses admin-only UI elements like the ecological override editor.

The public Labs index page at labs/index.php queries yea_lab_instruments for visible instruments and renders clickable cards for those in development or live status. The YEA site navigation includes a "YEA Labs" link. All public pages use the site's header, footer, and warm parchment palette, with ecoSPLAT design tokens scoped to #instrument-workspace to prevent CSS variable conflicts.

8. Planned Development

8.1 Lab 06: Pattern Analyst

The Pattern Analyst will provide cross-instrument and cross-site comparative analysis. With seven classification systems cached across 1,142 places, the system enables queries that traditionally required months of GIS work: which ecoregions share the same geology but differ in land cover? Where has NLCD diverged from LANDFIRE's vegetation classification? Which Mediterranean climate sites sit on sedimentary vs. volcanic substrate, and how does that correlate with species richness? The design of this instrument requires careful epistemological consideration of what constitutes a valid ecological comparison across heterogeneous data layers.

8.2 Research Session Management

The most significant planned feature is a research session system that transforms YEA Labs from a collection of individual instruments into an integrated research workflow. The concept:

Session Identity. A lightweight session token (UUID) stored in a cookie and URL. No user account required. A yea_research_sessions table tracks creation time and optional label.

Flagging. Each instrument gains a "Flag for Research" button, visible only when a session is active. Clicking it stores a data snapshot in yea_session_flags: session ID, place ID, instrument identifier, timestamp, and the specific data the user was viewing (normals, habitat profile, species counts). The session bar shows the flag count.

Session as Research Object. The accumulated flags create a research context — not saved data, but a record of what mattered to the researcher's question. This context feeds the Pattern Analyst for cross-instrument, cross-site synthesis.

This workflow — discover, characterize, flag, analyze, document, publish — appears to be without precedent in existing ecological informatics platforms. NatureServe's InSite generates single-site reports. GBIF provides occurrence data warehousing. Stanford's InVEST models ecosystem services. NCEAS tools offer workflow systems. None chain these capabilities into a session-based research workflow with AI-assisted interpretive synthesis across multiple analytical dimensions.

8.3 Lab 07: Research Notebook & Workflow Designer

The Research Notebook will serve as the session manager — reviewing flagged items, adding researcher notes, and organizing findings for export or analysis. This instrument represents the transition from analytical tools (Labs 01–06) to generative tools that produce research artifacts.

8.4 Lab 08: Journal & Publication Designer

The Journal will publish verified research findings as event-driven entries. Content appears because something ecologically noteworthy was discovered through the instrument workflow, not on a calendar schedule. AI-generated drafts undergo human verification before publication.

8.5 Strata AI Collaborator

Each instrument will integrate with Strata, the YEA AI collaborator, for interpretive synthesis. The existing YEA field guide demonstrates this capability with three narrative modes (ecological, geological, historical) generated from structured data scaffolds. In the Lab context, Strata will operate on the research session's flagged data to produce comparative analyses, identify patterns across sites, and generate draft research narratives for human review.

9. Limitations

US-specific sources (EPA Omernik, NLCD, LANDFIRE, PAD-US) are unavailable for international sites, reducing habitat characterization depth for the 698 non-US places. The Climate Analyst's archive fetch takes approximately 30 seconds per uncached place due to Open-Meteo Historical API response times for 34-year daily datasets. iNaturalist observation density varies dramatically by region, limiting biodiversity analysis in under-surveyed areas. The Köppen Climate API has no SLA. The LANDFIRE EVT endpoint times out intermittently.

The curated override system addresses API misclassification at ecotone boundaries and anthropogenically modified landscapes, but currently requires manual identification of misclassifications by an expert curator. Automated anomaly detection (e.g., flagging places where RESOLVE biome contradicts LANDFIRE vegetation type) is a planned capability for the Pattern Analyst.

10. Conclusion

YEA Labs demonstrates that a comprehensive ecological research instrument suite can be built on commodity web infrastructure without specialized GIS software, framework dependencies, or build pipelines. Five instruments are operational, sharing a common 1,142-place curated network enriched with eight geospatial classification layers. The filter drawer pattern, cross-instrument linking, and curated override system provide a consistent, professional research experience.

The planned research session and flagging system represents a novel contribution to ecological informatics — transforming the instrument suite from a collection of individual analytical tools into an integrated research workflow where the researcher's accumulated context becomes the input for cross-site, cross-instrument pattern analysis. This "multimodal UI reinforcement for the human in the loop" approach bridges the gap between automated data synthesis and expert ecological interpretation.

11. References

[1] Hamilton, M. P. (2026). "Your Ecological Address: System Architecture and Data Integration Specification." CNL-TN-2026-025, v4. Canemah Nature Laboratory.

[2] Hamilton, M. P. (2026). "YEA Labs: Research Instrument Architecture." CNL-FN-2026-029. Canemah Nature Laboratory.

[3] Dinerstein, E., Olson, D., Joshi, A., et al. (2017). "An Ecoregion-Based Approach to Protecting Half the Terrestrial Realm." BioScience, 67(6), 534–545.

[4] Peel, M. C., Finlayson, B. L., & McMahon, T. A. (2007). "Updated World Map of the Köppen-Geiger Climate Classification." Hydrology and Earth System Sciences, 11, 1633–1644.

[5] Karra, K., et al. (2021). "Global Land Use / Land Cover with Sentinel-2 and Deep Learning." 2021 IEEE IGARSS, 4704–4707.

[6] Omernik, J. M. & Griffith, G. E. (2014). "Ecoregions of the Conterminous United States: Evolution of a Hierarchical Spatial Framework." Environmental Management, 54(6), 1249–1266.

[7] iNaturalist (2026). https://www.inaturalist.org (accessed March 8, 2026).

[8] Mapbox (2026). "Mapbox GL JS." https://docs.mapbox.com (accessed March 8, 2026).

[9] Open-Meteo (2026). "Historical Weather API." https://open-meteo.com (accessed March 8, 2026).

12. Document History