File size: 7,509 Bytes
7e6579d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 | """Assemble the HF model repo folder runs/v1/hf_model: model files, predict.py, golden test, model card.
Golden test: 100 fixed feature rows + the outputs of predict.py; the serving side must reproduce them.
Also checks that predict.py (plain Booster, CPU) gives the same numbers as the training wrapper.
"""
from __future__ import annotations
import importlib.util
import json
import shutil
import sys
from pathlib import Path
import numpy as np
import pandas as pd
import xgboost as xgb
ROOT = Path("/root/trendex-ml")
RUN = ROOT / "runs" / "v1"
HF = RUN / "hf_model"
def load_module(path: Path, name: str):
spec = importlib.util.spec_from_file_location(name, path)
mod = importlib.util.module_from_spec(spec)
sys.modules[name] = mod
spec.loader.exec_module(mod)
return mod
def main() -> None:
HF.mkdir(parents=True, exist_ok=True)
for f in ["model_a.ubj", "feature_schema.json", "climatology.parquet", "weather_climatology.parquet",
"conformal.json", "metrics.json"]:
shutil.copy(RUN / f, HF / f)
shutil.copy(ROOT / "src" / "trendex_ml" / "predict.py", HF / "predict.py")
shutil.copy(ROOT / "configs" / "model_v1.yaml", HF / "model_v1.yaml")
# golden rows rebuilt with the training code itself
tr = load_module(ROOT / "scripts" / "30_train.py", "train_mod")
sel, arr = tr.load()
f = tr.build_features(sel, arr)
t = tr.table(f, tr.YEARS, tr.FEATURES).sample(100, random_state=0).reset_index(drop=True)
t.insert(0, "cell_id", sel["cell_id"].values[t["cell"].values])
golden_in = t[["cell_id", "year"] + tr.FEATURES]
(HF / "golden").mkdir(exist_ok=True)
golden_in.to_parquet(HF / "golden" / "inputs.parquet", index=False)
pm = load_module(HF / "predict.py", "predict_mod")
model = pm.load(HF)
out = model.predict(golden_in)
out.to_parquet(HF / "golden" / "expected.parquet", index=False)
ref = xgb.XGBRegressor()
ref.load_model(RUN / "model_a.ubj")
max_diff = float(np.max(np.abs(ref.predict(golden_in[tr.FEATURES]) - out["pred_anom"].values)))
print(f"golden: 100 rows, max |predict.py - training wrapper| = {max_diff:.2e}")
assert max_diff < 1e-5, "predict.py disagrees with the training model"
(HF / "test_golden.py").write_text('''"""pytest test_golden.py - the serving code must reproduce these outputs exactly."""
from pathlib import Path
import numpy as np
import pandas as pd
from predict import load
HERE = Path(__file__).parent
def test_golden():
m = load(HERE)
got = m.predict(pd.read_parquet(HERE / "golden" / "inputs.parquet"))
want = pd.read_parquet(HERE / "golden" / "expected.parquet")
assert np.allclose(got.values, want.values, atol=1e-6)
''')
write_card()
print("PACKAGE_DONE", sorted(p.name for p in HF.iterdir()))
def write_card() -> None:
m = json.loads((RUN / "metrics.json").read_text())
t, s = m["temporal_test"], m["spatial_test"]
fmt = lambda d: f"{d['point']:.3f} (95% CI {d['ci_lo']:.3f} to {d['ci_hi']:.3f}, {d['units']} units)" # noqa: E731
row = lambda name, d: f"| {name} | {d['xgb']['rmse']:.4f} | {d['ridge']['rmse']:.4f} | {d['clim']['rmse']:.4f} | " \
f"{d['xgb']['anomaly_corr']:.3f} | {d['ridge']['anomaly_corr']:.3f} | {d['xgb']['tercile_bacc']:.3f} |" # noqa: E731
abl = " -> ".join(f"{k}: {v:.3f}" for k, v in m["ablation_skill_vs_clim_temporal"].items())
imp = ", ".join(list(m["feature_importance_mean_abs"].keys())[:6])
card = f"""---
license: other
library_name: xgboost
tags: [nasa, modis, ndvi, imerg, gldas, pastures, kyrgyzstan, tabular-regression]
datasets: [TrendeX90/naryn-cube]
---
# TrendeX expected-greenness model (v1)
Predicts the **summer greenness (NDVI) anomaly** of every 1 km pasture cell in Naryn oblast, Kyrgyzstan
(May-September, 2001-2025) **from weather and terrain alone**. The gap between observed and expected NDVI is
change **not explained by precipitation, temperature, snow and soil moisture**. It is not a cause and says
nothing about forage quality. Built for NASA Space Apps 2026 ("Be An Earth System Trend Detective!").
## Inputs
- Weather anomalies vs each cell's 2001-2025 mean for the same month: GPM IMERG precipitation (month, 3-month,
Oct-Apr), MODIS LST day/night (month, previous month), MODIS snow (Mar-May, month), GLDAS soil moisture
(month) and April snow water.
- Terrain from NASADEM (elevation, spread, slope, steep share, aspect, TPI) and land cover (MCD12Q1 2020).
- The cell's own NDVI climatology for that month. **Not used on purpose:** year, coordinates, past NDVI.
## How it was tested (protocol locked in git before the first fit: `model_v1.yaml`, commit {m['git_commit']})
- Tuning only on 2001-2015 -> 2016-2019. The 2020-2025 years were used once, for the final test.
- Spatial test: 5-fold GroupKFold over ~30 x 30 km super-blocks (all years; easier than the temporal test
because the same years' weather appears in training).
- Baselines: climatology (anomaly = 0) and ridge regression on the same features.
- Pre-registered gate: ship XGBoost only if the 95% CI lower bound of its skill over ridge is > 0 on both tests.
**Gate passed: {m['gate']['passed']}. Shipped: {m['gate']['shipped_model']}.**
| Test | RMSE xgb | RMSE ridge | RMSE climatology | anomaly corr xgb | anomaly corr ridge | tercile bal. acc. xgb |
|---|---|---|---|---|---|---|
{row("Temporal (2020-2025)", t)}
{row("Spatial (unseen areas)", s)}
- Skill vs ridge, temporal: {fmt(t['skill_xgb_vs_ridge'])}. Five seeds: {t['seed_skill_vs_ridge']['mean']:.3f} +/- {t['seed_skill_vs_ridge']['sd']:.3f}.
- Skill vs ridge, spatial: {fmt(s['skill_xgb_vs_ridge'])}.
- Skill vs climatology, temporal: {fmt(t['skill_xgb_vs_clim'])}.
- What each NASA dataset adds (skill vs climatology, temporal test): {abl}.
- Most used inputs: {imp}.
## Limits (read before using)
- The model explains about a fifth of the year-to-year NDVI anomaly on unseen years; most variation is not weather-explained.
- P10-P90 band: on 2020-2025 it covered **{t['conformal_coverage_p10_p90']:.0%} instead of 80%**, so treat it as too narrow.
- Weather comes from coarse grids (IMERG 0.1 deg, GLDAS 0.25 deg) interpolated to 1 km.
- NDVI is greenness, not forage: shrub encroachment can look like improvement.
- Land cover is a fixed 2020 map; MODIS Terra drifted in recent years (see Aqua-Terra check in the dataset products).
- What-if runs: drier and hotter-than-normal conditions lower expected July NDVI, but wetter-than-normal
precipitation does not raise it (slightly lowers it on average). Treat what-if outputs as model
sensitivities, not causal effects.
- No field validation. Relative to Naryn pastures only.
## Use
```python
from predict import load
m = load(".") # needs only numpy, pandas, xgboost (CPU)
out = m.predict(features_df) # columns as in feature_schema.json
scen = m.what_if(cells, cell_ids, month=7, precip_pct=-30) # cells = naryn-cube cells.parquet
```
`pytest test_golden.py` reproduces the 100 golden rows.
## Data and tools
MOD13A3.061, MYD13A3.061, MOD11A2.061, MOD10A2.061, MCD12Q1.061, NASADEM_HGT.001 (LP DAAC / NSIDC via earthaccess),
GPM_3IMERGM.07 and GLDAS_NOAH025_M.2.1 (GES DISC). XGBoost, Optuna, scikit-learn, pymannkendall.
AI use: implementation was assisted by Claude (Anthropic); design decisions and the product idea are the team's.
"""
(HF / "README.md").write_text(card)
if __name__ == "__main__":
main()
|