Reference-normalize weather transmission scale factor (AH_ref + clamp)

[nugent68]

Summary

Refinement to the weather-dependent transmission model added in #150. The model

rho(T,AH) = p_max * exp(-beta_AH*AH - alpha_T*max(0,T-T0))

references the absolute-humidity exponential at AH = 0, which never occurs in the data (US min 0.13, p05 2.9 g/m³). So rho is far below 1 everywhere — US mean ≈ 0.20, even peak winter only ≈ 0.38. Since rho multiplies the calibrated baseline transmission probabilities (disease.p_trans / xmit_*) via prob = 1 - infect*xmit*rho, turning the weather model on suppresses effective transmission ~5× year-round and craters the calibrated R0.

Change

Move the exponential's reference point to a flu-season absolute humidity AH_ref (default 6.0 g/m³) and clamp the result to 1:

rho = min(1, p_max * exp(-beta_AH*(AH - AH_ref) - alpha_T*max(0,T-T0)))

With p_max = 1 the scale factor is 1 at/below AH_ref (and T <= T0), so the calibrated baseline is recovered during flu-season conditions and weather only attenuates toward summer. The clamp keeps 1 - infect*xmit*rho >= 0. Set AH_ref = 0 to recover the previous behaviour.

The model form (exponential decay in AH, T0 ~ 5 °C threshold) is unchanged and remains supported by Shaman & Kohn 2009, Peci et al. 2019, Park et al. 2020, and Lowen et al. 2007 — only the normalisation changes.

Verification

• rho over weatherData_US.csv (AH_ref=6, defaults): mean 0.47, winter (DJF) 0.81, summer (JJA) 0.13 (~6.3× swing), 22% of county-weeks at rho=1. Clamp invariant holds (max rho = 1, so 1 - infect*xmit*rho >= 0).

• 120-day MA simulation (inputs.ma, built locally):

  Run	Total infections	Final deaths
  do_weather=0 (baseline)	141,396	3,786
  AH_ref=6 (new default)	141,274	3,786
  AH_ref=0 (old behaviour)	42,225	1,323

  The new default reproduces the calibrated epidemic (winter-seeded outbreak burns through while rho≈1), whereas the old un-normalised reference suppressed it to ~30%.

Files

• src/WeatherTransmissionModel.H — AH_ref member + normalised/clamped compute, doc update
• src/WeatherTransmissionModel.cpp — parse weather_transmission.AH_ref
• docs/source/usage/how_to_run.rst — formula + AH_ref parameter docs
• examples/inputs_random_us_weather — commented AH_ref reference line

🤖 Generated with Claude Code