google-research / google-research/flood-forecasting
[BUG] cmal_deterministic._search_quantile contracts root bracket via frac_confine=0.8, clipping negative/tail quantiles
- Dominant language
- Python
- Stars
- 343
- Forks
- 87
- Avg merge
- 14d 23m
- Merged PRs (30d)
- 1
Description
**Location**
`googlehydrology/utils/cmal_deterministic.py:128-135`
**Root Cause Mechanism**
Clamping bounds are calculated via contraction factors (`0.8 * min(ppfs)` and `0.8 * max(ppfs)`). For negative values—common in standardized hydrologic target data and low-flow percentiles ($q \le 0.1$)—multiplying by $0.8$ shifts the lower bound upward toward zero. Restricting $k$ to this contracted interval prevents Newton-Raphson root-finding from reaching solutions in the true mixture domain $[\min(\text{PPF}), \max(\text{PPF})]$.
**Impact**
Distorts tail quantile forecasts (e.g., $q = 0.1$ low flows and $q = 0.9$ peak flood discharge) generated by the `cmal_deterministic` head by prematurely pinning estimates to artificial boundary limits.
**Suggested Fix**
Replace scalar contraction with an additive outward margin expansion:
```
min_ppf = torch.min(ppfs, dim=2, keepdim=True).values
max_ppf = torch.max(ppfs, dim=2, keepdim=True).values
margin = 0.1 * (max_ppf - min_ppf + 1e-6)
low = min_ppf - margin
high = max_ppf + margin
```
**Verification Checklist**
* [ ] Run unit tests on negative normalized inputs across edge percentiles ($q \in \{0.01, 0.05, 0.1, 0.9, 0.95, 0.99\}$).
* [ ] Verify Newton-Raphson iteration convergence rates on validation catchments without boundary clipping flags.
* [ ] Confirm broadcast tensor shapes along `dim=2` across multi-basin batched inference runs.
Contributor guide
Research direction
Start in googlehydrology/utils/cmal_deterministic.py:128-135 and inspect how _search_quantile computes its root bracket. Exercise the head with negative normalized inputs and edge percentiles q ∈ {0.01, 0.05, 0.1, 0.9, 0.95, 0.99}; done means Newton-Raphson converges without boundary clipping and broadcast shapes remain correct in multi-basin inference.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, pytorch
- Domain
- machine-learning
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100