Harmonize handling of codelists

[khaeru]

At the 2020-03-04 MESSAGE meeting, we discussed that several items in the ixmp data model are actually instances of a common concept. Namely:

• ‘unit’
• ‘region’ (name used for for the code list entries) / ‘node’ (name used for data dimensions).
• also, per Extend API to support dynamic time slices #264, ‘timeslice’ (name used for the code list entries) / ‘subannual’ (name used for data dimensions).
• also, per Meta support for model/scenario levels #353, ‘model name’ and ‘scenario name’.

Using the terminology of SDMX: these are 5 different codelists; lists of codes. Some are hierarchical (e.g. ‘node’); others are not. Some have only their short string ID; others also have a name (e.g. ‘node’), description, or annotation.

Currently, the ixmp.backend.base.Backend API has a proliferation of methods, each with slightly different semantics, for dealing with each of these. The proliferation of different types of objects in the data model makes it more costly to develop other, entirely open source Backends as alternatives to JDBCBackend, as targeted in #278

We should:

• Simplify the Backend interface (see here) by handling codes and lists of codes in a consistent way. These changes are invisible to the user; they just affect how a Platform talks to a Backend.

  • Add methods:

    • get_codes(codelist)
    • set_code(codelist, id, name=None, description=None, **attrs)
    • delete_code(codelist, id)

    Valid values will be:

    • for the codelist argument: 'node', 'timeslice' (or 'time_slice'?), 'unit', etc.
    • for attrs:
      • codelist='node': 'parent', 'hierarchy', 'mapped_to'.
      • codelist='timeslice': 'category', 'duration'.
      • codelist='unit': none.

  • Delete methods: get_nodes, get_timeslices, get_units, set_node, set_timeslice, set_unit, add_model_name, get_model_names, add_scenario_name, get_scenario_names.

• Update JDBCBackend:
  • Dispatch to whatever methods in the Java code of ixmp_source implement the Backend methods for the different codelists.
  • Calls like delete_code(...) will raise NotImplementedError where the functionality is lacking.
• Add to the Platform (without removing any existing behaviour):
  • an attribute like codelist, so that:
    • mp.codelist['region'] is the same as mp.get_regions(), etc.
  • A method add_code(...) with the same signature as Backend.set_code().

This should be addressed after #264 is completed and merged.

[khaeru]

• Updated the description as discussed at Meta support for model/scenario levels #353 (comment).
• Note that Handle 'annotations' as abstraction of 'docs' and 'metadata' #322, handling 'docs' and 'meta(data)' as annotations, was not merged with Bulk saving for metadata and exposing documentation API #314, but the branch and code are retained as examples for a future PR. That change is separate from the one described in this issue.