Improved (and changed?) feature for unit conversion

Daniel Huppmann

Dear pyam users,

We are continuously working on extending the features and tools provided by pyam and the number of contributors on GitHub is growing - but not all users are active on the GitHub repository, so let me reach out this way to gather feedback on a suggested API change.

## Current implementation

The current feature for unit conversion takes a dictionary of mappings:

df.convert_unit({'current_unit': ('target_unit', value)})

Advantage: multiple conversions possible with one command
Disadvantage: slightly cumbersome notation with a dictionary pointing to a tuple…

## Suggestion for new API

Playing around a bit, I suggest to change to the following:

df.convert_unit(current_unit, target_unit, factor=None)

where the conversion factor is used if given (similar to the current behaviour) - and we use the Python package pint to find the conversion factor for you for standard unit conversions like EJ to MWh, so that you don’t have to bother finding the right factor and inserting it in your script.

Advantage: easier notation, much better user experience for standard conversions
Disadvantage: the API change might break some already existing code in the future

## What do you think?

If you have any preference one way or another, please join the discussion on!

Thank you,