{
 "schema_version": 1,
 "about": "Fields of MEDUSA's open data at https://data.hydromedusa.fi/<country>/. Times are UTC (ISO 8601, minutes), levels in cm. Verdict codes: 0 not simulated, 1 no reading, 2 fine, 3 slight suspicion, 4 strong suspicion. Fields may be added; existing ones keep their meaning.",
 "docs": "https://hydromedusa.fi/about#open-data",
 "polling": "Files change once an hour. Send a file's ETag back as If-None-Match (or Last-Modified as If-Modified-Since): an unchanged file answers 304 with no body. HEAD gives size, ETag and Last-Modified without the body. To follow many gauges, poll status.json and read latest.json when it changes (about 13 KB gzip for every gauge; about 380 KB a day at one poll every 15 minutes) rather than one station API call per gauge; use api/station/<id>?days=1 for a gauge's newest day.",
 "files": {
  "status.json": {
   "what": "The newest hourly run.",
   "fields": {
    "country": "country code",
    "hour": "the hour this run is for",
    "t_end": "the newest 15-minute step the run computed",
    "result": "ok, late (too few inputs had reported; nothing written), or error",
    "code": "0 ok, other values: not ok",
    "last_good": "the hour of the newest ok run",
    "share_in": "share of the gauges with a reading near t_end (0-1)",
    "fetched": "readings fetched from the provider in this run",
    "stations": "gauges simulated",
    "skipped": "gauges not simulated",
    "skipped_reasons": "up to 20 skipped gauges with the reason",
    "latest_stations": "gauges in latest.json",
    "steps_slight": "slight steps written in this run",
    "steps_strong": "strong steps written in this run",
    "band_week": "the ISO week whose stored band (usual spread) judged the steps",
    "seconds": "run time",
    "timings": "seconds per stage of the run",
    "image": "the container image that ran",
    "silent_inputs": "input gauges that went silent and were filled from a similar gauge, and how many stations used a fill",
    "repair": "the self-repair after the run: the hole it worked on, the piece, rows and result",
    "absorbed": "only when it failed: the error of comparing the hour's fetch with the stored readings (revised, late or removed readings before the recomputed span are marked for recomputation)",
    "revisions": "once a day (the run of 02:00 UTC): the provider's readings re-fetched for the 7 days before the trailing span, how many changed, were added or were removed, at which stations, and the spans marked for recomputation",
    "reused": "when predictions were reused from the previous hour: windows reused and predicted"
   }
  },
  "latest.json": {
   "what": "The newest judged step of every gauge, by station id.",
   "fields": {
    "t": "the step",
    "state": "verdict code",
    "observed": "the reading, cm",
    "median": "the middle of the twins, cm",
    "lo": "the lowest twin, cm",
    "hi": "the highest twin, cm (the verdict is judged against lo-hi)"
   }
  },
  "meta.json": {
   "what": "Every gauge (country, t_end, stations by station id).",
   "fields": {
    "name": "gauge name",
    "river": "river or lake",
    "lat": "latitude (WGS 84)",
    "lon": "longitude (WGS 84)",
    "tolerance_cm": "how closely the twins follow the gauge, cm",
    "methods": "the twins (one per input ranking)",
    "inputs": "the gauges the twins read",
    "read_by": "the gauges whose twins read this one",
    "interval_min": "the gauge's logging interval, minutes",
    "filled_inputs": "inputs that were filled in the newest run, with their source"
   }
  },
  "summary.json": {
   "what": "The last 7 days (country, t_end, days, steps_per_day, stations, hourly, hourly_by_interval).",
   "fields": {
    "steps_per_day": "steps per day on the grid (96 for 15 minutes)",
    "stations.<id>.judged_24h": "steps judged in the last 24 h",
    "stations.<id>.slight_24h": "slight steps in the last 24 h",
    "stations.<id>.strong_24h": "strong steps in the last 24 h",
    "stations.<id>.slight_7d": "slight steps in the 7 days",
    "stations.<id>.strong_7d": "strong steps in the 7 days",
    "stations.<id>.last_flag": "the newest flagged step",
    "hourly[].t": "the hour",
    "hourly[].fine / slight / strong / none": "gauges by their most serious verdict in that hour",
    "hourly_by_interval.<minutes>": "the same hourly counts for the gauges that log at that interval, as arrays on hourly's hours"
   },
   "note": "stations lists only gauges flagged at least once in the 7 days"
  },
  "sim/<ISO week>.parquet": {
   "what": "Per gauge and 15-minute step of a week (Monday 00:00 UTC on).",
   "fields": {
    "station_id": "gauge",
    "time": "the step",
    "observed": "the reading, cm",
    "ensemble_median": "the middle of the twins, cm",
    "band_lo": "the lowest twin, cm",
    "band_hi": "the highest twin, cm",
    "qr_lo": "the gauge's usual spread, low edge, cm",
    "qr_hi": "the gauge's usual spread, high edge, cm",
    "state": "verdict code"
   }
  },
  "obs/<ISO week>.parquet": {
   "what": "The readings as fetched from the provider.",
   "fields": {
    "station_id": "gauge",
    "time": "the reading's time",
    "value": "the reading as the provider gives it",
    "unit": "the provider's unit of the value"
   }
  },
  "stations.parquet": {
   "what": "The provider's station list as fetched."
  },
  "band/<ISO week>.json": {
   "what": "The usual spread of every gauge, refitted when a week closes."
  },
  "cache/predictions_v1.parquet": {
   "what": "The previous hour's twin predictions, which the next run reuses where its inputs did not change (about 10 MB). Internal: its columns may change without notice; read sim/ for the results."
  },
  "lags.json": {
   "what": "Each gauge's publication delay as the hourly runs see it, so the silent-input fill can tell a gauge that publishes in batches from one that has gone silent.",
   "fields": {
    "t_end": "the run's end step these ages are measured at",
    "gauges.<id>.newest": "the time of the gauge's newest reading at that run",
    "gauges.<id>.age": "how old that reading was at the run's end step, hours",
    "gauges.<id>.waits": "the gauge's last completed waits, hours (the age its newest reading had when the next one arrived; up to the last 48)"
   },
   "note": "a gauge counts as silent only past both 3 h and its usual wait (the 90th percentile of its waits) plus an hour, once it has 12 waits"
  }
 },
 "api": {
  "station/<id>?days=n": {
   "what": "One gauge's series as JSON, n from 1 to 91 (default 7); ETag and 304 like the files.",
   "fields": {
    "station": "gauge",
    "from": "first step",
    "to": "last step",
    "step_minutes": "grid step",
    "t": "steps, milliseconds since 1970 UTC",
    "observed / median / band_lo / band_hi / qr_lo / qr_hi": "arrays on t, cm (as in sim)",
    "state": "verdict codes on t",
    "weeks": "the week files the answer was read from"
   }
  },
  "health": {
   "what": "200 while the newest ok run is recent enough, else 503 (for uptime checks)."
  }
 }
}
