Add a unit_mapping attribute to show a variable -> unit dictionary

[danielhuppmann]

Please confirm that this PR has done the following:

• [x] Tests Added
• [x] Documentation Added
• ~Name of contributors Added to AUTHORS.rst~
• [x] Description in RELEASE_NOTES.md Added

Description of PR

This PR adds an attribute unit_mapping to return a dictionary {variable: unit or list of units}. This is intended to replace the current function variables(include_units=True).

For illustration, the IamDataFrame

model	scenario	region	variable	unit	2005	2010
model_a	scen_a	World	Primary Energy	EJ/yr	1	6
model_a	scen_a	World	Primary Energy\|Coal	EJ/yr	0.5	3
model_a	scen_b	World	Primary Energy	GWh/yr	2	7

will return

df.unit_mapping
> {"Primary Energy": ["EJ/yr", "GWh/yr"], "Primary Energy|Coal": "EJ/yr"}

Unique unit for a variable?

Note that it may be preferable to require that an IamDataFrame has a unique unit for each variable (see the related discussion at #338). Currently, several units are allowed, so this PR simply maintains the current behavior.

[danielhuppmann]

I know that everyone is super-busy, but @gidden @znicholls @coroa, if you have a minute for a quick look just about the suggested API change, it would be very much appreciated...

[codecov[bot]]

Codecov Report

Merging #548 (740a721) into main (7d83a98) will increase coverage by 0.1%. The diff coverage is 100.0%.

@@           Coverage Diff           @@
##            main    #548     +/-   ##
=======================================
+ Coverage   93.4%   93.6%   +0.1%     
=======================================
  Files         48      48             
  Lines       5288    5299     +11     
=======================================
+ Hits        4942    4961     +19     
+ Misses       346     338      -8     

Impacted Files	Coverage Δ
tests/test_unfccc.py	100.0% <ø> (ø)
pyam/core.py	92.7% <100.0%> (+<0.1%)	:arrow_up:
tests/test_core.py	100.0% <100.0%> (ø)
tests/test_datareader.py	82.6% <0.0%> (+13.0%)	:arrow_up:
pyam/datareader.py	100.0% <0.0%> (+50.0%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 7d83a98...740a721. Read the comment docs.

[gidden]

lgtm! I have no strong feelings about the name, given that it is not simply a list like variables.

[znicholls]

Nice nice