Development practices
This page describes development practices for message_ix_models
and message_data
intended to help reproducibility, interoperability, and reusability.
In the following, the bold-face words required, optional, etc. have specific meanings as described in IETF RFC 2119.
On other pages:
Contributing to development in the MESSAGEix docs. All of these apply to contributions to
message_ix_models
andmessage_data
, including the Code style.Data, metadata, and configuration, for how to add and handle these.
On this page:
Advertise and check compatibility
There are multiple choices of the base structure for a model in the MESSAGEix-GLOBIOM family, e.g. different Node code lists and Years or time periods (year/*.yaml).
Code that will only work with certain structures…
must be documented, and include in its documentation any such limitation, e.g. “
example_func()
only produces data for R11 and year list B.”should use
check_support()
in individual pieces of code to pre-emptively check and raise an exception. This prevents inadvertent use of the code where its data will be invalid:
def myfunc(context, *args):
"""A function that only works on R11 and years ‘B’."""
check_support(
context,
dict(regions=["R11"], years=["B"]),
"Example data produced"
)
# … function code to execute if the check passes
Code may also check a Context
instance and automatically adapt data from certain structures to others, e.g. by interpolating data for certain periods or areas.
To help with validation, code that does this should log on the logging.INFO
level to advertise these steps.