sync embedded/arc_tz_weather from arc_tz_weather

Author: actionresearchprojects

embedded/arc_tz_weather/index.html

@@ -4,7 +4,7 @@
 """
 
 import math
-from datetime import datetime, timedelta
+from datetime import date, datetime, timedelta
 from pathlib import Path
 
 import pandas as pd
@@ -16,21 +16,99 @@
 LONGITUDE = 39.18
 SOLAR_CONSTANT = 1361  # W/m2
 
-# ── Beaufort Scale ────────────────────────────────────────────────────────────
+# ── Beaufort Scale (WMO definition, classified in knots) ──────────────────────
+# The Beaufort scale is defined in knots. All other units are derived using the
+# exact conversion factors below to avoid boundary errors.
+#
+# Exact conversion factors (from 1 nautical mile = 1852 m exactly):
+#   1 kn = 463/250 km/h   (= 1.852 km/h, exact rational value)
+#   1 kn = 463/900 m/s    (= 0.51444... m/s, exact rational value)
+KN_TO_KPH = 463 / 250   # km/h per knot
+KN_TO_MS  = 463 / 900   # m/s per knot
+KPH_TO_KN = 250 / 463   # knots per km/h
+MS_TO_KN  = 900 / 463   # knots per m/s
+
+# Thresholds in knots (WMO integer boundaries). range_kn is [lo, hi).
 BEAUFORT_SCALE = {
-    0: {"range": (0, 1), "label": "Calm"},
-    1: {"range": (1, 6), "label": "Light air"},
-    2: {"range": (6, 12), "label": "Light breeze"},
-    3: {"range": (12, 20), "label": "Gentle breeze"},
-    4: {"range": (20, 29), "label": "Moderate breeze"},
-    5: {"range": (29, 39), "label": "Fresh breeze"},
-    6: {"range": (39, 50), "label": "Strong breeze"},
-    7: {"range": (50, 62), "label": "Near gale"},
-    8: {"range": (62, 75), "label": "Gale"},
-    9: {"range": (75, 89), "label": "Strong gale"},
-    10: {"range": (89, 103), "label": "Storm"},
-    11: {"range": (103, 118), "label": "Violent storm"},
-    12: {"range": (118, 999), "label": "Hurricane"},
+    0:  {"range_kn": (0,   1),   "label": "Calm"},
+    1:  {"range_kn": (1,   4),   "label": "Light air"},
+    2:  {"range_kn": (4,   7),   "label": "Light breeze"},
+    3:  {"range_kn": (7,  11),   "label": "Gentle breeze"},
+    4:  {"range_kn": (11, 17),   "label": "Moderate breeze"},
+    5:  {"range_kn": (17, 22),   "label": "Fresh breeze"},
+    6:  {"range_kn": (22, 28),   "label": "Strong breeze"},
+    7:  {"range_kn": (28, 34),   "label": "Near gale"},
+    8:  {"range_kn": (34, 41),   "label": "Gale"},
+    9:  {"range_kn": (41, 48),   "label": "Strong gale"},
+    10: {"range_kn": (48, 56),   "label": "Storm"},
+    11: {"range_kn": (56, 64),   "label": "Violent storm"},
+    12: {"range_kn": (64, 999),  "label": "Hurricane force"},
+}
+
+# ── Wind Classification Systems ─────────────────────────────────────────────
+# All systems defined in their original published units.
+# Use the conversion constants above to convert to the working unit at runtime.
+#
+# native_unit: 'kn' = knots, 'ms' = m/s, 'computed' = derived from dataset.
+# bands: list of {label, lo, hi} where hi=None means no upper limit.
+WIND_CLASSIFICATIONS = {
+    "beaufort": {
+        "label": "Beaufort",
+        "native_unit": "kn",
+        "source": "WMO/Beaufort 1805",
+        "notes": "Sea-level scale; Bf 9-12 merged into Severe+ for pedestrian relevance. Force numbers available as metadata.",
+        "bands": [
+            {"label": "Calm",            "lo": 0,  "hi": 1,    "force": 0},
+            {"label": "Light Air",       "lo": 1,  "hi": 4,    "force": 1},
+            {"label": "Light Breeze",    "lo": 4,  "hi": 7,    "force": 2},
+            {"label": "Gentle Breeze",   "lo": 7,  "hi": 11,   "force": 3},
+            {"label": "Moderate Breeze", "lo": 11, "hi": 17,   "force": 4},
+            {"label": "Fresh Breeze",    "lo": 17, "hi": 22,   "force": 5},
+            {"label": "Strong Breeze",   "lo": 22, "hi": 28,   "force": 6},
+            {"label": "Near Gale",       "lo": 28, "hi": 34,   "force": 7},
+            {"label": "Gale",            "lo": 34, "hi": 41,   "force": 8},
+            {"label": "Severe+",         "lo": 41, "hi": None, "force": "9+"},
+        ],
+    },
+    "lawson": {
+        "label": "Lawson 2001",
+        "native_unit": "ms",
+        "source": "Lawson T.V., 2001, pedestrian comfort criteria, assessed at 1.5m height",
+        "notes": "Upper-bound thresholds. Use this version, not LDDC.",
+        "bands": [
+            {"label": "Sitting",          "lo": 0,  "hi": 4},
+            {"label": "Standing",         "lo": 4,  "hi": 6},
+            {"label": "Strolling",        "lo": 6,  "hi": 8},
+            {"label": "Business Walking", "lo": 8,  "hi": 10},
+            {"label": "Uncomfortable",    "lo": 10, "hi": None},
+        ],
+    },
+    "davenport": {
+        "label": "Davenport",
+        "native_unit": "ms",
+        "source": "Davenport A.G., 1975, first published pedestrian wind comfort criterion, exceedance probability 1.5%",
+        "notes": "Upper-bound thresholds.",
+        "bands": [
+            {"label": "Long Sitting",    "lo": 0,   "hi": 3.6},
+            {"label": "Short Sitting",   "lo": 3.6, "hi": 5.3},
+            {"label": "Walking Quietly", "lo": 5.3, "hi": 7.6},
+            {"label": "Walking Fast",    "lo": 7.6, "hi": 9.8},
+            {"label": "Uncomfortable",   "lo": 9.8, "hi": None},
+        ],
+    },
+    "percentile": {
+        "label": "Percentiles",
+        "native_unit": "computed",
+        "source": "WMO climatological quintile practice",
+        "notes": "Boundaries computed at runtime from the full available dataset. Quintile-based: P20, P50, P80, P95.",
+        "bands": [
+            {"label": "Calm",        "percentile_hi": 20},
+            {"label": "Light",       "percentile_lo": 20, "percentile_hi": 50},
+            {"label": "Moderate",    "percentile_lo": 50, "percentile_hi": 80},
+            {"label": "Strong",      "percentile_lo": 80, "percentile_hi": 95},
+            {"label": "Exceptional", "percentile_lo": 95},
+        ],
+    },
 }
 
 # ── 16-point Compass ─────────────────────────────────────────────────────────
@@ -228,10 +306,15 @@ def compass_bin(degrees, n_points=16):
 
 
 def beaufort_number(speed_kph):
-    """Return the Beaufort number for a given wind speed in km/h."""
+    """Return the Beaufort number for a given wind speed in km/h.
+
+    Classification is performed in knots (WMO definition) to avoid
+    boundary errors from rounded secondary-unit thresholds.
+    """
+    speed_kn = speed_kph * KPH_TO_KN
     for num, info in BEAUFORT_SCALE.items():
-        lo, hi = info["range"]
-        if lo <= speed_kph < hi:
+        lo, hi = info["range_kn"]
+        if lo <= speed_kn < hi:
             return num
     return 12
 
@@ -338,8 +421,11 @@ def build_available_periods(df):
         key = (d.year, s_idx)
         if key not in seen_seasons:
             seen_seasons.add(key)
+            _MONTH_ABBR = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
+            m_first = _MONTH_ABBR[SEASONS[s_idx]['months'][0] - 1]
+            m_last  = _MONTH_ABBR[SEASONS[s_idx]['months'][-1] - 1]
             seasons.append({
-                "label": f"{s_name} ({SEASONS[s_idx]['months'][0]}-{SEASONS[s_idx]['months'][-1]}) {d.year}",
+                "label": f"{s_name} ({m_first}\u2013{m_last}) {d.year}",
                 "year": d.year, "season": s_idx
             })
 
@@ -352,7 +438,7 @@ def build_available_periods(df):
         if key not in seen_weeks:
             seen_weeks.add(key)
             weeks.append({
-                "label": f"Week {iso_week}, {iso_year}",
+                "label": "W/s " + date.fromisocalendar(iso_year, iso_week, 1).strftime("%d/%m/%y"),
                 "year": iso_year, "week": iso_week
             })
 

embedded/arc_tz_weather/modules/common.py

@@ -7,7 +7,7 @@
 import numpy as np
 
 from .common import (
-    RAIN_INTENSITY_COLORS, RAIN_DAILY_COLORS,
+    RAIN_INTENSITY_COLORS, RAIN_DAILY_COLORS, TIMEZONE,
     detect_precip_resets, to_eat_ms, get_season_boundaries, compass_bin,
 )
 
@@ -89,17 +89,21 @@ def _compute_daily_rainfall(pdf):
         total = group["precip_incr"].sum()
         daily.append({
             "date": date,
-            "date_ms": int(pd.Timestamp(date).timestamp() * 1000),
+            "date_ms": int(pd.Timestamp(date).tz_localize(TIMEZONE).timestamp() * 1000),
             "total_mm": round(float(total), 2),
         })
     return daily
 
 
-def _detect_rain_events(pdf, gap_tolerance_min=15):
+def _detect_rain_events(pdf, gap_tolerance_min=15, min_depth_mm=0.5):
     """Detect rain events by grouping consecutive readings with rate > 0.
 
-    Allows gaps of up to gap_tolerance_min minutes.
+    Allows gaps of up to gap_tolerance_min minutes. Events with total depth
+    below min_depth_mm (WMO trace threshold) are excluded.
     """
+    # Compute median sampling interval for minimum duration fallback
+    median_interval_min = pdf["timestamp"].diff().dt.total_seconds().median() / 60
+
     raining = pdf["precip_rate_mmh"] > 0
     events = []
     in_event = False
@@ -127,19 +131,23 @@ def _detect_rain_events(pdf, gap_tolerance_min=15):
                 in_event = False
                 event_data = pdf.iloc[event_rows[0]:last_rain_idx + 1]
                 if len(event_data) > 0:
-                    events.append(_summarize_event(event_data, pdf))
+                    summary = _summarize_event(event_data, pdf, median_interval_min)
+                    if summary["total_mm"] >= min_depth_mm:
+                        events.append(summary)
                 event_rows = []
 
     # Handle event at end of data
     if in_event and event_rows:
         event_data = pdf.iloc[event_rows[0]:last_rain_idx + 1]
         if len(event_data) > 0:
-            events.append(_summarize_event(event_data, pdf))
+            summary = _summarize_event(event_data, pdf, median_interval_min)
+            if summary["total_mm"] >= min_depth_mm:
+                events.append(summary)
 
     return events
 
 
-def _summarize_event(event_data, full_df):
+def _summarize_event(event_data, full_df, min_duration_min=5):
     """Summarize a single rain event."""
     start = event_data["timestamp"].iloc[0]
     end = event_data["timestamp"].iloc[-1]

embedded/arc_tz_weather/modules/precipitation.py

@@ -9,7 +9,7 @@
 import numpy as np
 
 from .common import (
-    SOLAR_COLORS, LATITUDE, LONGITUDE, to_eat_ms,
+    SOLAR_COLORS, LATITUDE, LONGITUDE, TIMEZONE, to_eat_ms,
     extraterrestrial_radiation, get_season_boundaries,
 )
 
@@ -98,7 +98,7 @@ def _compute_daily_insolation(sdf):
         doy = pd.Timestamp(date).timetuple().tm_yday
         daily.append({
             "date": date,
-            "date_ms": int(pd.Timestamp(date).timestamp() * 1000),
+            "date_ms": int(pd.Timestamp(date).tz_localize(TIMEZONE).timestamp() * 1000),
             "insolation_kwh": round(kwh, 3),
             "day_of_year": doy,
         })
@@ -355,61 +355,75 @@ def _build_solar_distribution(sdf):
 
 
 def _build_clearness_index(daily_kt):
-    """Build clearness index scatter plot."""
+    """Build clearness index scatter plot.
+
+    Thresholds are calibrated for a humid tropical coastal site (Mkuranga, ~7S).
+    Standard temperate-climate thresholds (clear > 0.65, overcast < 0.35) are
+    inappropriate here: even on a genuinely clear day, high precipitable water
+    vapour and marine aerosols from the Indian Ocean suppress the clear-sky Kt
+    ceiling to approximately 0.55-0.65. Using temperate thresholds causes clear
+    days to be systematically mis-classified as partly cloudy.
+
+    References:
+    - Saunier, Reddy & Kumar (1987), Solar Energy 38(3): 169-177: generalised
+      Liu-Jordan CDCs are not suitable for tropical locations; Kmax must be
+      derived from local data.
+    - Udo (2000), Solar Energy 69(1): 45-53: tropical Nigerian site (~7N, same
+      latitude band) confirms Liu-Jordan inapplicability; highest recorded
+      clear-sky Kt was 0.64 after rainfall cleared aerosols.
+    - Diabate, Blanc & Wald (2004), Solar Energy 76(6): 733-744: Tanzania's
+      coastal zone falls in a humid low-Kt climate class with monthly mean
+      Kt typically 0.45-0.55 during dry-season months.
+    """
     if daily_kt.empty:
         return {"id": "clearness-index", "title": "Clearness Index",
                 "title_sw": "Fahirisi ya Uwazi", "data": [], "layout": {}}
 
     dates_ms = daily_kt["date_ms"].tolist()
     kt_vals = daily_kt["kt"].tolist()
 
-    # Color by category
-    colors = []
-    for kt in kt_vals:
-        if kt > 0.65:
-            colors.append("#2ca02c")  # clear
-        elif kt > 0.35:
-            colors.append("#ffbf00")  # partly cloudy
-        else:
-            colors.append("#4575b4")  # overcast
+    # Thresholds adjusted for humid tropical coastal climate (see docstring).
+    # Clear: Kt > 0.55, Partly cloudy: 0.25-0.55, Overcast: Kt <= 0.25
+    KT_CLEAR = 0.55
+    KT_OVERCAST = 0.25
 
     traces = [{
         "type": "scatter",
         "mode": "markers",
         "name": "Clearness Index (Kt)",
         "x_ms": dates_ms,
         "y": kt_vals,
-        "marker": {"color": colors, "size": 8},
+        "marker": {"color": "#000000", "size": 8},
     }]
 
     layout = {
         "yaxis": {"title": "Clearness Index (Kt)", "range": [0, 1]},
         "xaxis": {"title": "Date (EAT)"},
         "shapes": [
             {"type": "rect", "x0": 0, "x1": 1, "xref": "paper",
-             "y0": 0.65, "y1": 1, "fillcolor": "rgba(44,160,44,0.1)",
+             "y0": KT_CLEAR, "y1": 1, "fillcolor": "rgba(44,160,44,0.1)",
              "line": {"width": 0}},
             {"type": "rect", "x0": 0, "x1": 1, "xref": "paper",
-             "y0": 0.35, "y1": 0.65, "fillcolor": "rgba(255,191,0,0.1)",
+             "y0": KT_OVERCAST, "y1": KT_CLEAR, "fillcolor": "rgba(255,191,0,0.1)",
              "line": {"width": 0}},
             {"type": "rect", "x0": 0, "x1": 1, "xref": "paper",
-             "y0": 0, "y1": 0.35, "fillcolor": "rgba(69,117,180,0.1)",
+             "y0": 0, "y1": KT_OVERCAST, "fillcolor": "rgba(69,117,180,0.1)",
              "line": {"width": 0}},
         ],
         "annotations": [
-            {"x": 1.02, "xref": "paper", "y": 0.82, "text": "Clear",
+            {"x": 1.02, "xref": "paper", "y": 0.77, "text": "Clear",
              "showarrow": False, "font": {"size": 10, "color": "#2ca02c"}},
-            {"x": 1.02, "xref": "paper", "y": 0.5, "text": "Partly Cloudy",
+            {"x": 1.02, "xref": "paper", "y": 0.4, "text": "Partly Cloudy",
              "showarrow": False, "font": {"size": 10, "color": "#b8860b"}},
-            {"x": 1.02, "xref": "paper", "y": 0.17, "text": "Overcast",
+            {"x": 1.02, "xref": "paper", "y": 0.12, "text": "Overcast",
              "showarrow": False, "font": {"size": 10, "color": "#4575b4"}},
         ],
     }
 
     # Sky condition distribution
-    clear_pct = round((daily_kt["kt"] > 0.65).sum() / len(daily_kt) * 100, 1)
-    partly_pct = round(((daily_kt["kt"] > 0.35) & (daily_kt["kt"] <= 0.65)).sum() / len(daily_kt) * 100, 1)
-    overcast_pct = round((daily_kt["kt"] <= 0.35).sum() / len(daily_kt) * 100, 1)
+    clear_pct = round((daily_kt["kt"] > KT_CLEAR).sum() / len(daily_kt) * 100, 1)
+    partly_pct = round(((daily_kt["kt"] > KT_OVERCAST) & (daily_kt["kt"] <= KT_CLEAR)).sum() / len(daily_kt) * 100, 1)
+    overcast_pct = round((daily_kt["kt"] <= KT_OVERCAST).sum() / len(daily_kt) * 100, 1)
 
     return {
         "id": "clearness-index",
@@ -445,19 +459,6 @@ def _build_peak_solar_hours(daily_df):
     layout = {
         "yaxis": {"title": "Peak Solar Hours"},
         "xaxis": {"title": "Date (EAT)"},
-        "shapes": [{
-            "type": "line",
-            "x0": 0, "x1": 1, "xref": "paper",
-            "y0": 5.25, "y1": 5.25,
-            "line": {"color": "red", "width": 1, "dash": "dash"},
-        }],
-        "annotations": [{
-            "x": 1, "xref": "paper", "y": 5.25,
-            "text": "Coastal Tanzania typical (5-5.5 PSH)",
-            "showarrow": False,
-            "xanchor": "right",
-            "font": {"size": 10, "color": "red"},
-        }],
     }
 
     return {