Merge pull request #131 from defog-ai/geo-wind-humidity

Document the wind and humidity satellite datasets

Author: rishsriv

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "factiq",
   "description": "Answer economic and financial data questions with real data from FactIQ — official statistics, market data, earnings-call transcripts, executive media appearances, central-bank speeches and minutes, a curated business-news feed, and satellite-derived data (nighttime lights, shipping and port activity, reservoir levels, crop fires and wildfires with mappable footprints, NO2/SO2/CO activity, smoke and dust aerosol, monsoon rainfall) — return sourced answers, chart JSON, or report JSON.",
-  "version": "0.41.3",
+  "version": "0.42.0",
   "author": {
     "name": "FactIQ",
     "url": "https://www.factiq.com"

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "factiq",
   "description": "Answer economic and financial data questions with real FactIQ data — official data, markets, earnings calls, executive media appearances, central-bank documents, and satellite-derived signals including crop fires and wildfires — then return sourced answers, chart JSON, or report JSON.",
-  "version": "0.41.3",
+  "version": "0.42.0",
   "author": {
     "name": "FactIQ",
     "url": "https://www.factiq.com"

evals/mocks/factiq/_tools.json

@@ -414,7 +414,7 @@
         "additionalProperties": false,
         "properties": {
           "dataset": {
-            "description": "Satellite dataset. One of:\n- \"fires_viirs\": active fire detections and fire radiative power (NASA FIRMS, 2012->, one day behind). Covers crop-residue burning, forest fires, and flaring.\n- \"no2_tropomi\": tropospheric NO2 column (Sentinel-5P, 2018->, ~3 days), an industrial/traffic activity proxy. Check valid_obs_share; cloudy intervals below 0.2 are weakly supported.\n- \"so2_tropomi\": SO2 column (Sentinel-5P, 2018->, ~3 days) for coal power, smelting, refining, and volcanoes. Noisy away from strong sources; track trends rather than absolute background levels.\n- \"co_tropomi\": CO column (Sentinel-5P, 2018->, ~3 days) for biomass/crop burning and industrial combustion. CO drifts across borders and is seasonal, so compare the same season across years.\n- \"aerosol_index_tropomi\": UV aerosol index (Sentinel-5P, 2018->, ~3 days) for smoke, dust, and haze. It is dimensionless; sustained values above ~1 indicate heavy smoke or dust, and it works over clouds.\n- \"ndvi_s2\": cloud-masked vegetation NDVI (Sentinel-2, 2017->, ~2-5 days), a crop-condition signal. Check valid_obs_share and compare the same season across years.\n- \"precip_chirps\": gauge-calibrated rainfall (CHIRPS, 1981->, ~2 days, 50S-50N) for monsoon, drought, and flood risk.\n- \"precip_imerg\": rainfall totals (NASA IMERG V07 Late, 2000->, ~1-2 days, global at 0.1 degree). Use where CHIRPS has no coverage; daily and monthly values are rainfall totals.\n- \"temperature_power\": mean/max/min 2m air temperature (NASA POWER, 1981->, ~3 days) for heatwaves and energy demand.\n- \"soil_moisture_power\": root-zone soil wetness from 0 to 1 (NASA POWER, 1981->, ~3 days) for agricultural drought.",
+            "description": "Satellite dataset. One of:\n- \"fires_viirs\": active fire detections and fire radiative power (NASA FIRMS, 2012->, one day behind). Covers crop-residue burning, forest fires, and flaring.\n- \"no2_tropomi\": tropospheric NO2 column (Sentinel-5P, 2018->, ~3 days), an industrial/traffic activity proxy. Check valid_obs_share; cloudy intervals below 0.2 are weakly supported.\n- \"so2_tropomi\": SO2 column (Sentinel-5P, 2018->, ~3 days) for coal power, smelting, refining, and volcanoes. Noisy away from strong sources; track trends rather than absolute background levels.\n- \"co_tropomi\": CO column (Sentinel-5P, 2018->, ~3 days) for biomass/crop burning and industrial combustion. CO drifts across borders and is seasonal, so compare the same season across years.\n- \"aerosol_index_tropomi\": UV aerosol index (Sentinel-5P, 2018->, ~3 days) for smoke, dust, and haze. It is dimensionless; sustained values above ~1 indicate heavy smoke or dust, and it works over clouds.\n- \"ndvi_s2\": cloud-masked vegetation NDVI (Sentinel-2, 2017->, ~2-5 days), a crop-condition signal. Check valid_obs_share and compare the same season across years.\n- \"precip_chirps\": gauge-calibrated rainfall (CHIRPS, 1981->, ~2 days, 50S-50N) for monsoon, drought, and flood risk.\n- \"precip_imerg\": rainfall totals (NASA IMERG V07 Late, 2000->, ~1-2 days, global at 0.1 degree). Use where CHIRPS has no coverage; daily and monthly values are rainfall totals.\n- \"temperature_power\": mean/max/min 2m air temperature (NASA POWER, 1981->, ~3 days) for heatwaves and energy demand.\n- \"soil_moisture_power\": root-zone soil wetness from 0 to 1 (NASA POWER, 1981->, ~3 days) for agricultural drought.\n- \"wind_power\": 10m wind speed, daily maximum, eastward and northward components, the direction the wind blows from, and a 0-1 steadiness score (NASA POWER, 1981->, ~3 days). Use it to separate weather from emission changes in air-pollution data and to trace where smoke comes from.\n- \"humidity_power\": 2m relative humidity in % (NASA POWER, 1981->, ~3 days), a weather control for haze and fine particles.",
             "type": "string"
           },
           "region": {

references/data/satellite.md

@@ -4,7 +4,8 @@ Satellite-derived indicators, fetched live from the provider and aggregated
 over a region server-side. Use them when official statistics are too slow for
 the question or don't cover it: crop burning as it happens, industrial
 activity from emissions, smoke and haze episodes, monsoon rainfall by state,
-heatwaves, agricultural drought.
+heatwaves, agricultural drought, and the wind and humidity that explain
+changes in air pollution.
 
 Read this before the first `get_geo_data` call in a session.
 
@@ -40,6 +41,8 @@ sections below. Passing either for another dataset is an error.
 | `precip_imerg` | Rainfall (NASA IMERG V07 Late, 0.1°) | Global drought, flood, and water-supply context where CHIRPS has no coverage | 2000→ | ~1–2 days |
 | `temperature_power` | 2 m air temperature mean/max/min (NASA POWER, MERRA-2 0.5°) | Heatwaves → electricity demand, labour productivity, crop stress | 1981→ | ~3 days |
 | `soil_moisture_power` | Root-zone soil wetness 0–1 (NASA POWER, MERRA-2) | Sowing conditions and agricultural drought ahead of production data | 1981→ | ~3 days |
+| `wind_power` | 10 m wind speed, daily maximum, eastward (`u_wind_ms`) and northward (`v_wind_ms`) components, direction the wind blows from (`wind_from_deg`), steadiness 0–1 (NASA POWER, MERRA-2 0.5°) | Whether a change in NO₂, CO or smoke comes from emissions or from weather (strong wind dilutes pollution); which way smoke travels (pair with `fires_viirs`); wind conditions for wind-power output | 1981→ | ~3 days |
+| `humidity_power` | 2 m relative humidity, % (NASA POWER, MERRA-2 0.5°) | Weather control for haze and fine particles, which grow in humid air; heat stress together with `temperature_power` | 1981→ | ~3 days |
 
 ## Regions
 
@@ -197,6 +200,14 @@ vegetation fires either way, so the newest data is never silently missing.
 - POWER datasets are 0.5° reanalysis — honest at state/country scale, blind to
   city microclimates. Very small or very large regions sample the centroid
   cell (a `notes` entry appears for large ones).
+- `wind_power`: `wind_from_deg` is the bearing the wind blows **from**
+  (0 = north, 90 = east, 270 = west), computed from the average of the
+  wind components over the region and the interval. Winds from opposite
+  directions cancel, so read `wind_steadiness` first: near 1 the wind kept
+  one direction; below ~0.3 it kept changing and the direction says little.
+  Over a large region, winds in different parts also cancel — use a state or
+  a bbox, not a whole country, to say where smoke came from.
+  `wind_speed_ms` is the average speed and is not affected by this.
 - `notes` can also report partially failed fetches ("may undercount — retry").
   Retry once before using such a result.