Add guidance on variable and region naming

iamc.rst

@@ -37,8 +37,8 @@ the `pyam package <https://pyam-iamc.readthedocs.io/en/stable/api/io.html>`_).
 
 .. figure:: _static/iamc-example.png
 
-   Illustrative example of IAMC-format timeseries data |br|
-   via the `IAMC 1.5°C Scenario Explorer`_
+   Illustrative example of IAMC-format timeseries data
+   from the `IAMC 1.5°C Scenario Explorer`_
 
 .. _`CD-LINKS`: https://www.cd-links.org
 
@@ -56,6 +56,15 @@ mappings across projects.
 
 Visit https://github.com/IAMconsortium/common-definitions for more information.
 
+Variable & region naming guidance
+---------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   iamc/variable
+   iamc/region
+
 Related software packages
 -------------------------
 

iamc/region.rst

@@ -0,0 +1,30 @@
+The *region* column
+===================
+
+Common regions
+--------------
+
+In model-comparison projects, it is useful to define *common regions* that can be
+computed consistently from original model results. Widely used examples are the
+`R5, R9 and R10 regions`_.
+
+.. _`R5, R9 and R10 regions`: https://github.com/IAMconsortium/common-definitions/blob/main/definitions/region/common.yaml
+
+Naming conventions for native model regions
+-------------------------------------------
+
+In contrast to common regions used for comparison or scenario analysis across models,
+each model has a "native region" resolution.
+
+Models with a coarse spatial resolution should add a model-specific identifier to the
+native model regions (e.g., `MESSAGEix-GLOBIOM 1.1|North America`) to avoid confusion
+when comparing results to other models with similar-but-different regions.
+
+If a model has a country-level resolution (where disambiguation is not a concern),
+we recommend to *not add* a model identifier.
+
+For country-level regional resolution, the :class:`nomenclature` package provides
+a standardized list of `country names`_ based on the :class:`pycountry` package
+(`link <https://github.com/flyingcircusio/pycountry>`_) and the ISO 3166-1 standard.
+
+.. _`country names` : https://nomenclature-iamc.readthedocs.io/en/stable/api/countries.html

iamc/variable.rst

@@ -0,0 +1,40 @@
+The *variable* column
+=====================
+
+The 'variable' column of the IAMC format describes the type of information represented
+in the specific timeseries. The variable name implements a "semi-hierarchical" structure
+using the :code:`|` character (*pipe*, not l or i) to indicate the structure or "depth".
+Names (should) follow a structure like *Category|Subcategory|Specification*.
+
+Semi-hierarchical means that a hierarchy can be imposed, e.g., one can enforce
+that the sum of *Emissions|CO2|Energy* and *Emissions|CO2|Other*
+must be equal to *Emissions|CO2* (if there are no other *Emissions|CO2|…* variables).
+
+However, this is not mandatory, e.g., the sum of *Primary Energy|Coal*,
+*Primary Energy|Gas* and *Primary Energy|Fossil* should not be equal
+to *Primary Energy* because this would double-count fossil fuels.
+
+Variable naming conventions
+---------------------------
+
+A variable name should adhere to the following conventions:
+
+*  A *|* (pipe) character indicates levels of hierarchy.
+*  Do not use spaces before and after the *|* character, but add a
+   space between words (e.g., *Primary Energy|Non-Biomass Renewables*).
+*  Do not use abbreviations (e.g, *PHEV*) unless strictly necessary.
+*  Do not use abbreviations of statistical operations (*min*, *max*,
+   *avg*) but always spell out the term.
+*  All words must be capitalised (except for *and*, *w/*, *w/o*, etc.).
+*  Add hierarchy levels where it might be useful in the future, e.g.,
+   use *Electric Vehicle|Plugin-Hybrid* instead of *Plugin-Hybrid
+   Electric Vehicle*.
+*  Do not include words like *Level* or *Quantity* in the variable,
+   because this should be clear from the context or unit.
+
+Units
+-----
+
+The **unit** attribute is **required** and its value should be compatible with the
+`iam-units <https://github.com/iamconsortium/units>`_ package. Alternatively,
+a variable can be *dimensionless*, i.e., not have a unit.