Remove deprecated signature of creating data frames in tutorials with make_df

[LauWien]

Using the new signature to create the data frame with the make_df() function in the tutorials might increase the understanding of them.
As I understood correctly the old signature needs the following code to create the data frame (e.g. data frame from the westeros_emissions_bounds tutorial):

base_emission_factor = {
    'node_loc': country,
    'year_vtg': vintage_years,
    'year_act': act_years,
    'mode': 'standard',
    'unit': 'tCO2/kWa',
} 

emission_factor = make_df(base_emission_factor, technology= 'coal_ppl', emission= 'CO2', value= 7.4)

Which can also be achieved by the new signature without the need to build a dictionary to append:

emission_factor = make_df("emission_factor", 
                           node_loc=country, 
                           year_vtg=vintage_years, 
                           year_act=act_years, 
                           mode='standard', 
                           unit='tCO2/kWa', 
                           technology= 'coal_ppl',
                           emission= 'CO2', 
                           value= 7.4 )

Any thoughts @OFR-IIASA and @khaeru?
I'm happy to change it, if wanted.

[OFR-IIASA]

I think that the routine overall is ok and it will help to clean up the tutorials..BUT...
For us it is self explanatory what is happening when using the function make_df. For new users though, this has always resulted in confusion as new users need to in most cases try and wrap their head around two things - the model structure as well as in many cases "pandas".
I would therefore suggest two things. If making changes to the tutorials, then the make_df function should be "introduced" and therefore explained in more detail.
Secondly, as observed in the follow-up discussions on the last capacity building workshop, when we add parameters where the index includes both vintage and activity years, then in the past we have just added activity years that stretch the entire model horizon, irrespective of the lifetime of the technology. This definitely needs to be fixed as this causes too much confusion for new users.

[khaeru]

For us it is self explanatory what is happening when using the function make_df. For new users though, this has always resulted in confusion as new users need to in most cases try and wrap their head around two things - the model structure as well as in many cases "pandas".
I would therefore suggest two things. If making changes to the tutorials, then the make_df function should be "introduced" and therefore explained in more detail.

This can be handled in multiple ways:

1. Expand the "Examples" section of the documentation I wrote for make_df: https://docs.messageix.org/en/stable/api.html#message_ix.util.make_df to add more examples of different ways of calling the function and the outcomes. In these, link to the Python docs on using keyword arguments (https://docs.python.org/3/tutorial/controlflow.html#keyword-arguments) and/or to tutorials that teach these.
2. Split some or all of those examples into a new page in the "Developing MESSAGEix models" section of the docs, e.g. with a title like "Prepare parameter data". Link from the function docs to the page and vice versa. Here's a similar kind of page from the genno docs: https://genno.readthedocs.io/en/latest/cache.html#basics
3. Add to or expand tutorials, as suggested.

These are in order of preference, i.e. (3) is the least preferable. Tutorials are the slowest part of the test suite and are less easy to access than (1) and (2) directly in the docs. Per (2), the docs can be just as narrative or descriptive as a tutorial.

Secondly, as observed in the follow-up discussions on the last capacity building workshop, when we add parameters where the index includes both vintage and activity years, then in the past we have just added activity years that stretch the entire model horizon, irrespective of the lifetime of the technology. This definitely needs to be fixed as this causes too much confusion for new users.

This could be handled with the current issue, but could also be dealt with separately.