google-research / google-research/flood-forecasting

[BUG] cmal_deterministic._search_quantile contracts root bracket via frac_confine=0.8, clipping negative/tail quantiles

Open
#274 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.