Skip to content

bioepic-data/ecosim-agent / .agents/skills/ameriflux-site-info

ameriflux-site-info

Verified

Extract AmeriFlux site metadata and map it to EcoSIM JSON variables. Use when a task needs site latitude, longitude, elevation, mean annual temperature, Koppen climate code, or vegetation type for an AmeriFlux site ID or flux-site name.

AmeriFlux Site Info Extractor

Use When

  • You need EcoSIM site metadata for an AmeriFlux site ID such as US-Ha1.
  • You need to map flux-site attributes into ALATG, ALONG, ALTIG, ATCAG, IETYPG, or IXTYP1.
  • You are building site-level inputs before climate, atmospheric chemistry, or soil extraction.

Constraints

  • NEVER use it extract climate data.

Purpose

Automate the identification and derivation of site-specific attributes (e.g., location, vegetation) from AmeriFlux site pages and map the extracted values to EcoSIM variables. The bundled script uses cached EcoSIM site JSON first, then structured AmeriFlux page text or rendered DOM extraction when a refresh is needed.

Workflow

  1. Resolve the AmeriFlux site ID or site name.
  2. Load existing result/<SITE_ID>/<SITE_ID>_ecosim_site.json metadata when present.
  3. Extract latitude, longitude, elevation, mean annual temperature, Koppen-Geiger code, and IGBP vegetation type.
  4. Map the extracted values to EcoSIM JSON variables and write under result/<SITE_ID>/.
  5. Check units: latitude/longitude are decimal degrees, elevation is meters, and temperature is degrees Celsius.

Metadata Extraction Policy

Use deterministic sources in this order:

  1. Existing local EcoSIM site metadata JSON.
  2. AmeriFlux siteinfo HTML fetched with Python standard library URL tools, or requests when available.
  3. Rendered AmeriFlux DOM text fetched with Playwright if the static HTML is incomplete.

Always inspect the extracted values for physical and ecological plausibility before using them in EcoSIM inputs.

Location Cross-Checks

Before using metadata for driving-data preparation, also follow ../ecosim-data-readiness/references/site_conflicts.md: reconcile site-filtered field records and terrain/history with cached metadata and generated inputs. Location/sign checks alone do not validate soil, terrain or management defaults.

For slope/aspect, follow the terrain-evidence review. Preserve magnitude, direction, spatial support and unavailable evidence separately. A cached reference aspect is not established by a site's slope description or by the field being located east/west of another field.

For a soil-preparation task, also inspect site-filtered BIF GRP_SOIL_TEX and GRP_SOIL_CHEM records. Preserve group associations, units evidence, depth/date and missing metadata for the soil workflow; the site-metadata extraction script does not perform this comparison. Route texture/carbon selection to field_soil_evidence.md before treating a mapped profile as representative of the field.

AmeriFlux pages put each value on its own line under a label (Lat, Long: then -16.4980, -56.4120). Line cleanup must never strip a leading minus sign: an earlier version did, turning southern latitudes (BR-Npw, CL-SDF), sub-zero MAT (US-Brw -12.6, US-Prr -2), and below-sea-level elevation (US-Myb -4) positive. Every extraction is now cross-checked, and the result is stored in _location_validation:

CheckEvidenceOn failure
page_signsEach parsed latitude, longitude, elevation, and MAT appears with the same sign in the raw page text under its labelerror
country_boundsCoordinates fall inside the envelope of the country in the site-ID prefix (BR-, CL-, US-, ...); the message says when the opposite sign would fiterror
description_regionRegion words in the site Description or name (South America, Pantanal, Amazon, Patagonia, Alaska, Arctic, ...) agree with the latitudewarning
koppen_consistencyMAT lies in a plausible range for the Koppen group (A 15 to 35, C -3 to 30, D -25 to 16, E -60 to 8 degC); tropical classes within 35 deg latitudewarning
koppen_from_coordinatesThe page Koppen class appears in the 3x3 neighbourhood of the parsed coordinates on a gridded Beck et al. (2018) Koppen-Geiger map; when it fits the opposite-sign latitude or longitude instead, the warning says to suspect a lost minus signwarning

The Koppen map is a NetCDF with ids(lat, lon) indexing a labels list, such as the ILAMB regions/Koppen.nc 0.5-degree product (Beck et al. 2018, Sci. Data 5:180214). Pass --koppen-raster PATH, set ECOSIM_KOPPEN_RASTER, or place it at data/Koppen.nc; without it the check reports not_available. A plain mismatch (e.g. US-MMS page Cfa, map Dfa) usually reflects a class boundary or a different climatology, so it is a warning, not a coordinate error.

Errors stop the extraction without writing JSON. Cached JSON is validated too; a cached file that fails is refetched automatically. Use --skip-location-check only after confirming the coordinates by hand. Warnings are printed and kept in the JSON; review them before building forcing. The checks are offline and catch sign and gross-location errors, not small coordinate errors inside the right country.

1. Site Metadata Extraction (Flux Network)

Given an AmeriFlux site name or ID (e.g., "Blodgett Forest" or "US-Blo"), read cached metadata or parse the rendered AmeriFlux site page text, then map the extracted values to the required EcoSIM JSON variables.

JSON VariableSource AttributeDescription
ALATGSite LatitudeDecimal degrees north.
ALONGSite LongitudeDecimal degrees east.
ALTIGElevationMeters above sea level.
ATCAGMATMean Annual Temperature (°C).
IETYPGClimate ClassKoppen-Geiger climate zone code.
IXTYP1IGBP TypeDominant vegetation type (mapped to plant litter flags).

Logic for Vegetation Mapping:

  • If IGBP is ENF (Evergreen Needleleaf) → Set IXTYP1 to 9 or 11 (Coniferous).
  • If IGBP is DBF (Deciduous Broadleaf) → Set IXTYP1 to 8 or 10 (Deciduous).

Koppen climate classification mapping: Using the koppenDict mapping, convert the site's Koppen-Geiger code (e.g., "Csa") to the corresponding integer code for IETYPG. This will allow the model to apply appropriate climate-specific parameters during simulations.

koppenDict = { "Af": 11, "Am": 12, "As": 13, "Aw": 14, "BWk": 21, "BWh": 22, "BSk": 26, "BSh": 27, "Cfa": 31, "Cfb": 32, "Cfc": 33, "Csa": 34, "Csb": 35, "Csc": 36, "Cwa": 37, "Cwb": 38, "Cwc": 39, "Dfa": 41, "Dfb": 42, "Dfc": 43, "Dfd": 44, "Dsa": 45, "Dsb": 46, "Dsc": 47, "Dsd": 48, "Dwa": 49, "Dwb": 50, "Dwc": 51, "Dwd": 52, "ET": 61, "EF": 62 }

2. Implementation & Execution

Prerequisites

  • Python 3.8+
  • requests: Optional HTTP fetch helper; the script also has a standard-library HTTP fallback.
  • Playwright: Optional fallback for rendered DOM extraction when static HTML is incomplete.

Setup for the Bundled Local Script

pip install playwright requests
playwright install chromium

No local vision service is required.

Usage

To execute the skill, run the following command from the project root. The resulting JSON will be saved under ./result/<SITE_ID>/ by default:

python .agents/skills/ameriflux-site-info/extract_ameriflux_site_data.py <SITE_ID>

Example:

python .agents/skills/ameriflux-site-info/extract_ameriflux_site_data.py US-Ha1

To bypass cached metadata and refresh from AmeriFlux:

python .agents/skills/ameriflux-site-info/extract_ameriflux_site_data.py US-Ha1 --force-refresh

Output

The script creates a JSON file named result/<SITE_ID>/<site_name>_ecosim_site.json with the following structure:

{
  "site_name": "US-Ha1",
  "ALATG": 40.0,      # Latitude (decimal degrees north)
  "ALONG": -120.0,    # Longitude (decimal degrees east)
  "ALTIG": 1000.0,    # Elevation (meters above sea level)
  "ATCAG": 10.0,      # Mean Annual Temperature (°C)
  "IETYPG": 34,       # Koppen climate zone code
  "IXTYP1": 10        # Vegetation type code
}

Optional precipitation climatology

When the site page provides mean annual precipitation, preserve it as mean_annual_precip_mm with precipitation_reference (the source URL/path). Do not substitute the forcing's own mean or infer a missing value from another metadata field. Older cached records may lack MAP; the forcing workflow must then obtain a sourced reference or report precipitation plausibility unverified. This field is a climatological comparison reference, not an annual rain target.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall