A new naming system for variables is being introduced in CMIP7, referred to as branded variables. The new system retains the familiar short variable names used in earlier CMIP phases to denote a physical quantity (pr for precipitation, for example). It introduces a new metadata attribute, termed the branding suffix, that describes how a variable is sampled temporally and spatially. The new naming system is intended to make it easier to find the variables you want. The branding suffix is a global metadata attribute, and is used in the output filenames and directory path structures of CMIP7 datasets.

For comparison with the previous CMIP naming scheme for variables, consider the global monthly-mean near-surface air temperature, which in CMIP6 was denoted as tas in the Amon MIP table (a MIP table is also sometimes referred to as a CMOR table). A compound name constructed from these terms, Amon.tas, uniquely identifies the variable in the collection of all CMIP6 variables. The Amon table is a collection of atmospheric variables at monthly frequency, and other MIP tables (Omon, SImon, ...) collect together other variables that usually are similar in realm, frequency, and region. While familiar to experienced users of CMIP data, this system led to a proliferation of table names in CMIP6 due to the large number of requested variables (~2000), and the rationale for their names was not always clear (for example, table name Amon included the realm while 3hr and day used only the frequency).

The branded variable corresponding to Amon.tas is tas_tavg-h2m-hxy-u. The short name, tas, identifies the physical quantity and is in this example unchanged. The short name is also referred to as the "root name" of the branded variable. The branding suffix, tavg-h2m-hxy-u, describes how the variable is temporally and spatially sampled and is composed of four parts:

• temporal label: tavg indicates a time average.
• vertical label: h2m indicates near-surface at 2m above ground.
• horizontal label: hxy indicates a horizontal field spanning latitude and longitude.
• area label: u indicates "unmasked".

Branding suffixes are always composed of these four labels. The possible values for each type of label are tabulated below.

Importantly, tas_tavg-h2m-hxy-u is not fully equivalent to Amon.tas. This is because a branded variable name does not identify a requested variable's frequency or its region. By additionally specifying the frequency as monthly, and the region as global, tas_tavg-h2m-hxy-u then becomes equivalent to Amon.tas. The same branded variable could alternately be reported at other frequencies or for other regions. For example, tas_tavg-h2m-hxy-u reported on a global grid and at daily frequency is denoted day.tas in CMIP6.

The branded variable approach (Taylor et al., in preparation) aims to be more systematic and scalable to future CMIP phases and wider use across community MIPs and other WCRP projects. CMOR tables keyed by branded variable name define the metadata characteristics of variables apart from the frequency, region, or specific grids on which these variables should be reported. Guidance on reporting grids for CMIP output is given here. The metadata conventions for describing grids in the CMIP7 CVs are explained in the Essential Model Documentation guidance pages.

Variable names¶

There are several CMIP7 metadata attributes that may be referred to as a "variable name", depending on the context. For example, the name of a branded variable does not specify its frequency or region. Similarly, the short name of a physical quantity such as pr does not specify how it is spatiotemporally sampled (i.e., it lacks the information conveyed by a branding suffix). To disambiguate the different flavours of variable name used in the CMIP7 Data Request and CVs, a brief glossary is provided here:

• variable_id is the short name of a physical quantity that is familiar to many users from previous CMIP phases (e.g., tas, pr, sos). It is a mandatory global attribute.
• root name refers to the first component of a branded variable name (e.g., tas_tavg-h2m-hxy-u), and is always identical to variable_id.
• out_name is found in CMOR tables where it specifies the name of the data variable in a CMORized netcdf file, and is always identical to variable_id.
• physical parameter name is the short name used in the CMIP7 Data Request to identify a physical quantity, with an associated CF standard name. It is the "Name" column in the "Physical Parameters" table of the Airtable view of the Data Request. It is usually equivalent to the root name (i.e., the variable_id), which is given by the "variableRootDD" column in the "Physical Parameters" table. However there are a number of exceptions, which are tabulated below.
• branded_variable is composed of the root name followed by a branding suffix (e.g., tas_tavg-h2m-hxy-u), as described above. It is a mandatory global attribute.
• Data Request variable refers to a requested variable specified by a row in the "Variables" table of the Airtable view of the Data Request. A requested variable corresponds to a single branded_variable, but additionally specifies the frequency, region, and reporting grid (atmosphere, ocean, ...) on which the variable should be provided.
• CMIP7 compound name uniquely identifies a Data Request variable in the CMIP7 Data Request. It is composed of four parts: realm, root name, branding suffix, frequency, and region (e.g. atmos.tas.tavg-h2m-hxy-u.mon.glb). The four latter parts of the CMIP7 compound name - essentially the branded variable plus frequency and region - are required to uniquely identify a Data Request variable in the collection of CMIP7 requested variables. The realm is not strictly required for uniqueness, but is included in the compound name so that users can easily identify requested variables associated with a given realm. The realm used in the CMIP7 compound name is the primary realm identifed by the "Modelling Realm - Primary" column in the "Variables" table of the Airtable view of the Data Request. The primary realm is also used to group variables in the CMIP7 CMOR tables.
• CMIP6 compound name is another unique identifier of Data Request variables in the CMIP7 Data Request, and is included because these names are familiar to many users (e.g., Amon.tas, day.pr, Omon.tos) and may help them navigate the transition to the new CMIP7 variable naming scheme based on branded variables. If a variable was included in CMIP6 then this name uniquely identifies it in the CMIP6 Data Request, but note that newly introduced variables in CMIP7 are also assigned a CMIP6 compound name (hence there is a one-to-one mapping between CMIP6 compound name and CMIP7 compound name). This flavour of compound name is composed of the name of a CMIP6-era MIP table (also referred to as a CMOR table) followed by short name that is usually identical to the physical parameter name (e.g., Amon.tas). There are some exceptions, tabulated below, in which extra information is appended to the end of the short name (e.g., Amon.tasSouth30). However, the short variable name used in the CMIP6 compound name always begins with the physical parameter name.

Branding suffixes¶

The four components of the branding suffix are derived from variable metadata using the cmip-branded-variable-mapper python package. The following tables show the meaning of each element of a branding suffix. Each of these labels is a mandatory global attribute written to output netCDF files (temporal_label, vertical_label, horizontal_label, area_label).

Temporal labels¶

The temporal_label identifies how the variable is sampled in the time domain: time average, instantaneous, etc.

Vertical labels¶

The vertical_label identifies how the variable is sampled in the vertical domain: on pressure levels, model levels, at a single level, etc. It is set to u (unspecified) if none of the following apply (e.g. a field reported at the surface or at the top of the atmopsphere).

Horizontal labels¶

The horizontal_label identifies how the variable is sampled horizontally: function of latitude and longitude, only latitude, site data, etc. Note that this label does not denote a particular choice of reporting grid (e.g., a 1° × 1° latitude-longitude grid). Guidance on reporting grids can be found here.

Area labels¶

The area_label identifies the unmasked area type for which data are reported: sea ice, land, ice sheet, etc. It is set to u (unmasked) if no masking is applied.

Physical parameter name changes¶

The following table lists root names in the CMIP7 Data Request (v1.2.2.3) that do not match one and only one physical parameter name (recall that root name is the same as variable_id and out_name). Out of the 987 root names in Data Request v1.2.2.3 there are 119 such cases (12%). For each such root name, the table lists the physical parameter name(s) and the CMIP6 compound name(s) of the Data Request variable(s) using this root name.