Update README.md

README.md

@@ -1,22 +1,31 @@
 ---
 license: mit
 tags:
-- forcast
+- forecast
 - weather
 - lstm
 - classification
 - regression
-- weather-forcast
+- weather-forecast
 - multitask
 - harley-ml
 ---
 
 # Hweh-6M
 
+## Summary
 
+Task: Weather Forecasting  
+Inputs: 72 hours time-series  
+Outputs: 12h multivariate forecast  
+Params: 6M  
+Framework: PyTorch & Transformers  
+Author: Paul Courneya (Harley-ml)
 
-**Hweh-6M** is a **6-million-parameter LSTM model** trained to predict the next **12 hours of weather**, including temperature, humidity, pressure, precipitation, and more, using the previous **72 hours of weather context**.
-We recommend using this model as a backup to a weather API or for offline forecasting when internet access is unavailable.
+## Description
+
+**Hweh-6M** is a **6-million-parameter LSTM model** trained to predict the next **12 hours of weather**, including temperature, humidity, pressure, precipitation, and more, using the previous **72 hours of weather context**.  
+We recommend using this model as a backup to a weather API or for offline forecasting when internet access is unavailable.  
 However, this model was primarily trained to serve as a teacher for [Hweh-446k](https://huggingface.co/Harley-ml/Hweh-446k).
 
 We would also like to give a shoutout to [**Open-Meteo**](https://open-meteo.com/) for providing a **free-to-use weather forecasting API**.
@@ -33,7 +42,7 @@ The model uses a multitask LSTM setup:
 | `hidden_dim`            | `384`                                          |
 | `num_layers`            | `6`                                            |
 | `dropout`               | `0.1`                                          |
-| `encoder_type`          | `lstm`                                       |
+| `encoder_type`          | `lstm`                                         |
 | `num_locations`         | `82`                                           |
 | `location_emb_dim`      | `32`                                           |
 | `num_weather_classes`   | `7`                                            |
@@ -112,6 +121,16 @@ We trained Hweh-6M on 4.06 million rows of weather data from 82 locations for on
 
 ## Generation Examples
 
+| ID | Class        |
+| -- | ------------ |
+| 0  | clear        |
+| 1  | cloudy       |
+| 2  | fog          |
+| 3  | drizzle      |
+| 4  | rain         |
+| 5  | snow         |
+| 6  | thunderstorm |
+
 City=Seattle
 ```
 {
@@ -232,7 +251,7 @@ City=Nuuk
       "precipitation_mm": 0.9192219972610474,
       "pressure_msl_hpa": 999.2293090820312,
       "surface_pressure_hpa": 984.041015625,
-      "cloud_cover_pct": 100.66844177246094,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 22.042539596557617,
       "rain_probability": 0.9964759945869446,
       "weather_class": 5,
@@ -257,7 +276,7 @@ City=Nuuk
       "precipitation_mm": 0.8211548924446106,
       "pressure_msl_hpa": 998.41796875,
       "surface_pressure_hpa": 983.3368530273438,
-      "cloud_cover_pct": 100.51109313964844,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 21.754901885986328,
       "rain_probability": 0.9918462634086609,
       "weather_class": 5,
@@ -282,7 +301,7 @@ City=Nuuk
       "precipitation_mm": 0.7267112731933594,
       "pressure_msl_hpa": 997.7637939453125,
       "surface_pressure_hpa": 982.8118286132812,
-      "cloud_cover_pct": 100.73283386230469,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 21.31927490234375,
       "rain_probability": 0.9851851463317871,
       "weather_class": 5,
@@ -307,7 +326,7 @@ City=Nuuk
       "precipitation_mm": 0.6503503322601318,
       "pressure_msl_hpa": 997.3221435546875,
       "surface_pressure_hpa": 982.2531127929688,
-      "cloud_cover_pct": 100.4798583984375,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 20.908214569091797,
       "rain_probability": 0.9797365069389343,
       "weather_class": 5,
@@ -332,7 +351,7 @@ City=Nuuk
       "precipitation_mm": 0.5726789832115173,
       "pressure_msl_hpa": 997.1259155273438,
       "surface_pressure_hpa": 982.1145629882812,
-      "cloud_cover_pct": 101.23336791992188,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 20.37297821044922,
       "rain_probability": 0.9752851724624634,
       "weather_class": 5,
@@ -357,7 +376,7 @@ City=Nuuk
       "precipitation_mm": 0.4950953722000122,
       "pressure_msl_hpa": 997.0792236328125,
       "surface_pressure_hpa": 981.837646484375,
-      "cloud_cover_pct": 101.33966064453125,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 19.884090423583984,
       "rain_probability": 0.9711479544639587,
       "weather_class": 5,
@@ -382,7 +401,7 @@ City=Nuuk
       "precipitation_mm": 0.43851515650749207,
       "pressure_msl_hpa": 997.214111328125,
       "surface_pressure_hpa": 981.5133666992188,
-      "cloud_cover_pct": 101.732666015625,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 19.454288482666016,
       "rain_probability": 0.9665488600730896,
       "weather_class": 5,
@@ -407,7 +426,7 @@ City=Nuuk
       "precipitation_mm": 0.38016656041145325,
       "pressure_msl_hpa": 997.3843994140625,
       "surface_pressure_hpa": 981.6067504882812,
-      "cloud_cover_pct": 101.74685668945312,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 19.01665496826172,
       "rain_probability": 0.9600462913513184,
       "weather_class": 5,
@@ -432,7 +451,7 @@ City=Nuuk
       "precipitation_mm": 0.3401757478713989,
       "pressure_msl_hpa": 997.632568359375,
       "surface_pressure_hpa": 981.5086059570312,
-      "cloud_cover_pct": 101.2756118774414,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 18.69092559814453,
       "rain_probability": 0.9514879584312439,
       "weather_class": 5,
@@ -457,7 +476,7 @@ City=Nuuk
       "precipitation_mm": 0.29920822381973267,
       "pressure_msl_hpa": 997.88671875,
       "surface_pressure_hpa": 981.637451171875,
-      "cloud_cover_pct": 101.19945526123047,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 18.297332763671875,
       "rain_probability": 0.9422094821929932,
       "weather_class": 5,
@@ -482,7 +501,7 @@ City=Nuuk
       "precipitation_mm": 0.2678143382072449,
       "pressure_msl_hpa": 998.099853515625,
       "surface_pressure_hpa": 981.798583984375,
-      "cloud_cover_pct": 100.46200561523438,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 17.996307373046875,
       "rain_probability": 0.9368607401847839,
       "weather_class": 5,
@@ -507,7 +526,7 @@ City=Nuuk
       "precipitation_mm": 0.23492039740085602,
       "pressure_msl_hpa": 998.2453002929688,
       "surface_pressure_hpa": 981.8583374023438,
-      "cloud_cover_pct": 100.22344970703125,
+      "cloud_cover_pct": 100.0,
       "wind_speed_10m_kmh": 17.61905860900879,
       "rain_probability": 0.9265281558036804,
       "weather_class": 5,
@@ -533,9 +552,34 @@ City=Nuuk
 }
 ```
 
-## Note
+### Note
+In observed outputs, the model is often within **0.3°C** of the actual value.
+
+Furthermore, you can pass locations that are not present in the model’s location embedding table. We’ve observed that the model can generalize to out-of-distribution (OOD) cities, with an estimated accuracy drop of only about 2–5%. However, this figure is an estimate and does not reflect a true ground-truth measurement.
+
+## Use Cases
+
+Intended for:
+
+1. Backup to API
+2. Offline forecasting if you have the data
+3. Research
+4. Or more simply, for fun
+
+Not intended for:
 
-You can pass locations that are not present in the model’s location embedding table. We’ve observed that the model can generalize to out-of-distribution (OOD) cities, with an estimated accuracy drop of only about 2–5%. However, this figure is an estimate and does not reflect a true ground-truth measurement.
+1. Safety-critical forecasting (aviation, emergency response)
+2. Replacing meteorological or API services
+
+## Limitations
+
+1. The model is not perfectly accurate and will produce approximate forecasts rather than exact real-world weather conditions.
+2. Prediction accuracy decreases as the forecast horizon increases up to 12 hours.
+3. Performance may degrade on unseen or underrepresented geographic regions and climate types.
+4. The model does not enforce physical laws of atmospheric dynamics and may produce physically inconsistent outputs.
+5. Forecast quality is sensitive to the quality and completeness of input weather data.
+6. Rare or extreme weather events are underrepresented in training data and may be poorly predicted.
+7. Weather class outputs are simplified and do not capture fine-grained meteorological distinctions.
 
 # Inference
 
@@ -801,6 +845,10 @@ def cyc(x: np.ndarray, period: float) -> tuple[np.ndarray, np.ndarray]:
     return np.sin(angle), np.cos(angle)
 
 
+def clamp_array(x: np.ndarray, lo: float | None = None, hi: float | None = None) -> np.ndarray:
+    return np.clip(x, lo, hi)
+
+
 def request_with_backoff(session: requests.Session, url: str, params: dict[str, Any]) -> dict[str, Any]:
     last_exc: Exception | None = None
     for attempt in range(MAX_RETRIES):
@@ -922,6 +970,13 @@ def build_single_sequence(df: pd.DataFrame) -> np.ndarray:
     visibility = np.nan_to_num(df["visibility"].astype(float).to_numpy(), nan=0.0)
     wind = np.nan_to_num(df["wind_speed_10m"].astype(float).to_numpy(), nan=0.0)
     wind_dir = np.nan_to_num(df["wind_direction_10m"].astype(float).to_numpy(), nan=0.0)
+
+    humidity = clamp_array(humidity, 0.0, 100.0)
+    cloud_cover = clamp_array(cloud_cover, 0.0, 100.0)
+    precip = clamp_array(precip, 0.0, None)
+    wind = clamp_array(wind, 0.0, None)
+    visibility = clamp_array(visibility, 0.0, None)
+
     wind_dir_sin, wind_dir_cos = cyc(wind_dir, 360.0)
     weather_bucket = df["weather_code"].fillna(1).apply(weather_code_to_bucket).to_numpy(dtype=np.int64)
 
@@ -1070,6 +1125,12 @@ def predict():
         weather_probs = torch.softmax(weather_logits, dim=-1).squeeze(0).detach().cpu().numpy()
         weather_idx = np.argmax(weather_probs, axis=-1).astype(np.int64)
 
+        humidity_pred = np.clip(humidity_pred, 0.0, 100.0)
+        cloud_cover_pred = np.clip(cloud_cover_pred, 0.0, 100.0)
+        precip_pred = np.clip(precip_pred, 0.0, None)
+        wind_pred = np.clip(wind_pred, 0.0, None)
+        rain_prob = np.clip(rain_prob, 0.0, 1.0)
+
     context_start = df["time"].iloc[0]
     context_end = df["time"].iloc[-1]
     requested_at_utc = pd.Timestamp.now(tz="UTC")