Ouranosinc / xclim / 6042074519

90%

main: 92%

push

github

Partial and relative unit declarations (#1414)

<!--Please ensure the PR fulfills the following requirements! -->
<!-- If this is your first PR, make sure to add your details to the
AUTHORS.rst! -->
### Pull Request Checklist:
- [ ] This PR addresses an already opened issue (for bug fixes /
features)
    - This PR fixes #xyz
- [x] Tests for the changes have been added (for bug fixes / features)
- [x] (If applicable) Documentation has been added / updated (for bug
fixes / features)
- [x] CHANGES.rst has been updated (with summary of main changes)
- [x] Link to issue (:issue:`number`) and pull request (:pull:`number`)
has been added

### What kind of change does this PR introduce?

* `declare_units` can accept relative declaration. For example
`thresh="<tas>"` means that `thresh` should have the same dimensions as
`tas`. More complex declarations are possible : `thresh="<tas> / <pr>"`
or `thresh="[length] / <tas> "`.
* It can also be only _partially_ declared with `partial=True`. In that
case, the passed dimensions are stored in the wrapper, but the
`check_units` code is not injected.

Both additions are useful for "generic" indices. For example:
```
@declare_units(partial=True, threshold="<data>")
def spell_length(
    data: xr.DataArray, threshold: Quantified, reducer: str, freq: str, op: str
) 
```
Here, `spell_length` already "knows" that the `threshold` should have
the same units (dimensions) as `data`, but we still haven't declare
those. Different indicators can be created from the function, each one
either explicitly re-wrapping with `declare_units(data="...")` or simply
using `Indicator`'s `input` argument to map `data` to a known variable.

Another change this brings is an additional `dimensions` field in
`variable.yml`. I realized that Indicators using `input` to map generic
inputs to precipitation variables were not "aware" that the "hydro"
context could be used. This was because the mapping was passing... (continued)

89 of 97 new or added lines in 5 files covered. (91.75%)

8316 of 9172 relevant lines covered (90.67%)

3.48 hits per line