ENH: Update convert_units_to function

[bzah]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR fixes Convert [length] into [length]/[time] when cell_methods and/or standard_name allows it #1205
• Tests for the changes have been added (for bug fixes / features)
  • (If applicable) Documentation has been added / updated (for bug fixes / features)
• HISTORY.rst has been updated (with summary of main changes)
  • Link to issue (:issue:number) and pull request (:pull:number) has been added
• The relevant author information has been added to AUTHORS.rst and .zenodo.json

What kind of change does this PR introduce?

This PR adds standard-name-aware unit conversions. Those are listed in data/variables.yml in a new "conversions" section. For now, the amount2rate and the new amount2lwethickness are available (and reverse operations).

convert_units_to will also perform those conversion automatically if the change in dimensionality requires it and the input has a valid standard name.

The new functions are often the equivalent of the "hydro" context. Both are complementary: the hydro context is still to be used in indicators for which the transformation is implicitly valid, no matter the CF attributes.

This is necessary to be able to compute precipitation indices on datasets that express RR as "thickness_of_rainfall_amount" instead of the usual "precipitation_flux" such as the e-obs datasets.

I can't make these transformations available automatically in the indices with the current structure state of declare_units, I'll look into this in a future PR. For now, as shown in the edited units.ipynb these "CF conversions" must be down explicitly beforehand.

Does this PR introduce a breaking change?

Yes, the error pint.errors.DimensionalityError is no longer raised when attempting to convert this kind of datasets described above into a [length] / [time] compatible unit.

[bzah]

A more generalist approach could be to do something like (pseudo-code):

if  is_amount(source) and is_rate(target):
  src_rate = amount2rate(source)
  return convert(src_rate, target)
elif is_rate(source) and is_amount(target):
   src_amount rate2amount(source)
   return convert(src_amount, target)

That would work for "thickness_of_rainfall_amount" case, but also for any attempted conversion between an amount and a rate.

WDYT ?

[aulemahal]

Nice thanks!
Apart from my comment on amount2rate, I think this automatic behaviour is right in xclim's scope.

I was going to suggest to open this up to all other thickness/amount<->rate/flux conversions, but I realized that would need extra care because of the non-liquid precipitation where the amount<->rate and thickness<->flux conversions are non-trivial.
If we were to add them, I think the machinery would be more complex and differentiate between all 4 categories and their possible conversions.
(Recall : amount= [kg m-2], thickness=m, rate=[m s-1] and flux=[kg m=2 s=1])

[huard]

@aulemahal Ready for final review. Should we add a test for irregular time series to confirm it fails ?

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[aulemahal]

Woupsi sorry.

[aulemahal]

@huard and the others, I believe this is ready!

I edited the top post to explain what was done here. Grosso modo : Instead of abel's units-based hook into converts_units_to, I chose to go with a metadata-based conversion with it's own functions. convert_units_to can also make use of these. Unit conversion that changes the dimensionality is now possible, but requires valid standard names.

[bzah]

Nice to see this being merge 🎉
Thanks for taking over on this PR!