bioepic-data/ecosim-agent / .agents/skills/ameriflux-site-info
ameriflux-site-info
VerifiedExtract 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| extract_ameriflux_site_data.py | script | 30.4 KB |
| test_extract_ameriflux_site_data.py | script | 9.9 KB |
SKILL.md
View on GitHub---
name: ameriflux-site-info
description: 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](../ecosim-data-readiness/references/terrain_evidence.md).
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`](../ameriflux-surgo-grid-extract/references/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`:
| Check | Evidence | On failure |
| --- | --- | --- |
| `page_signs` | Each parsed latitude, longitude, elevation, and MAT appears with the same sign in the raw page text under its label | error |
| `country_bounds` | Coordinates fall inside the envelope of the country in the site-ID prefix (`BR-`, `CL-`, `US-`, ...); the message says when the opposite sign would fit | error |
| `description_region` | Region words in the site Description or name (South America, Pantanal, Amazon, Patagonia, Alaska, Arctic, ...) agree with the latitude | warning |
| `koppen_consistency` | MAT 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 latitude | warning |
| `koppen_from_coordinates` | The 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 sign | warning |
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 Variable | Source Attribute | Description |
| :--- | :--- | :--- |
| **ALATG** | Site Latitude | Decimal degrees north. |
| **ALONG** | Site Longitude | Decimal degrees east. |
| **ALTIG** | Elevation | Meters above sea level. |
| **ATCAG** | MAT | Mean Annual Temperature (°C). |
| **IETYPG** | Climate Class | Koppen-Geiger climate zone code. |
| **IXTYP1** | IGBP Type | Dominant 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
```bash
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:
```bash
python .agents/skills/ameriflux-site-info/extract_ameriflux_site_data.py <SITE_ID>
```
Example:
```bash
python .agents/skills/ameriflux-site-info/extract_ameriflux_site_data.py US-Ha1
```
To bypass cached metadata and refresh from AmeriFlux:
```bash
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:
```jsonc
{
"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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |