Variable Names

As described before, to the degree variables have been used in previous applications and are thus part of the variable library, they should simply be picked from that list. Only in case where the required variables cannot be found in the library, new variable names and definitions should be constructed.

General Rules for constructing new variable names

The construction of variable names follows a few basic rules to ensure consistency in structure of new variable names with existing ones. These rules are summarized below.

• Variables names should be kept as short as possible while at the same time being as self-explanatory as possible to minimize the possibility of misinterpretations without having to read the exact definitions.
• The first part of a variable name should define what the variable represents as opposed to being a structuring element (e.g., a sector) that combines several variables into a group of variables. In other words, the first part of the variable name should answer the question what type of indicator it is dealing with (e.g., an efficiency, energy use at a specific level, land cover of a certain type)
• Different parts of variable names, including structural or hierarchical elements, are separated by a separator �|�.
• Hierarchical structures in the variable names can be useful to add structure to variable names. On the other hand, too excessive use of such hierarchical structures should be avoided to keep variable names short. At the same time, there are often multiple hierarchies possible, i.e., multiple ways of structuring the variable tree exist. Therefore, in general the rule should be to use not more than two hierarchical levels in the construction of variable names (e.g., �Liquids|Petroleum Products� can be broken down into �Liquids|Diesel� and �Liquids|Gasoline� instead of �Liquids|Petroleum Products|Diesel� and �Liquids|Petroleum Products|Gasoline�).
• In case different aggregates need to be constructed that cut across several categories of an existing hierarchy, the aggregates should be introduced at the same hierarchy level as the ones they are competing with (e.g., �Fossil� is the aggregate of �Coal�, �Oil� and �Gas�, �Solids� is the aggregate of �Biomass� and �Coal� and both would be introduced at the same level of the hierarchy).
• In particular, for aggregates of two groups of variables (e.g., sectors) a new aggregated group can be constructed by joining the original sector names with an �and� (e.g., the energy end-use sectors �Residential� and �Commercial� are often reported jointly as �Residential and Commercial�, emissions for �Energy Supply� and �Energy Demand� can be aggregated into �Energy Supply and Demand�). These aggregates should also be placed at the same level of the hierarchy as the original groups to avoid proliferation of hierarchical levels.
• �Other� variables should be added for all variable categories to allow modelers to allocate variables that do not match any of the predefined categories. To document what is included in such �Other� variables, the comment sheet of the data template should be used.

Variable Subcategories and Additivity

An important feature of the data template is it's hierachical variables structure which was introduced to document how variables can be broken down to sub-variables which in turn should again add up to the higher level variable. At the same time, it is often possible to break down a certain variable along different dimensions. For example, final energy use can be broken by fuel or by sector, and fossil primary energy can be broken down by fuel (e.g., coal, oil, gas) or by applications with and with out carbon capture and storage (CCS). These examples illustrate that embedding all possible breakdowns of variables into sub-categories is impossible and using a hierachical structure through multiple levels would also create exessively long variable names. Therefore, generally not more than two hierarchical levels should be used in the construction of variable names.

To illustrate the hierachical structure of the variables, in particular in the domains of energy (primary, secondary, and final) and emissions, graphs like the one presented below (Figure 1) are used as part of this guidance material. This sample variable tree shows that Variable A is the sum of Variable A1 through Variable A5 with Variable A2 and Variable A4 being broken down furhter into Variable A2i to Variable A2ii and Variable A4i to Variable A4iii, respectively.

Figure 1: generic sample variable tree

This concept of additivity of sub-variables to higher level variables holds for the majority of extensive variables in the energy and emissions variable categories and is documented for the most important variable categories on the following pages of this website. Intensive quantities such as prices, levelized costs or specific capital costs are obviously excluded from this additivity rule, even though the hierarchical structure is also used in their naming convention.

A few critical variable domains in which reporting errors are frequently made are the energy and emissions reporting, in particular at the regional level where im- and exports need to be taken into account for both energy carriers and the associated emissions (see also Common Errors). In this section some general guidlines for the energy and emissions reporting are provided.