<a id="cmor-tables"></a>

# Variables and CMOR Tables

ESMValCore has been designed to facilitate working with
[Earth System Model](https://www.climateurope.eu/earth-system-modeling-a-definition/)
data, also known as climate model data.
To make it easy to compare and combine data from different climate models,
reanalysis datasets, and observational datasets, ESMValCore uses the standardized
variables from the
[CMOR tables](https://github.com/ESMValGroup/ESMValCore/tree/main/esmvalcore/cmor/tables)
provided by the projects it supports. [CMOR](https://github.com/PCMDI/cmor)
(Climate Model Output Rewriter) is a tool commonly used by climate modelling
centers to format their model output according to community standards.
The CMOR tables define the standardized variable names, units,
coordinates, and other metadata for various climate variables and are typically
compiled from a Data Request and a Controlled Vocabulary, e.g. the
[CMIP7 CMOR tables](https://github.com/WCRP-CMIP/cmip7-cmor-tables/) are
based on the
[CMIP7 Data Request](https://wcrp-cmip.org/cmip-phases/cmip7/cmip7-data-request/),
and the
[CMIP7 Controlled Vocabulary](https://github.com/WCRP-CMIP/CMIP7-CVs)
.
ESMValCore comes bundled with several CMOR tables, which are stored in the directory
[esmvalcore/cmor/tables](https://github.com/ESMValGroup/ESMValCore/tree/main/esmvalcore/cmor/tables).
It is possible to [configure which CMOR tables are used by ESMValCore](../quickstart/configure.html.md#cmor-table-configuration).

The [facets](facets.html.md#facets) `project`, `mip`, `short_name`, and optionally
`branding_suffix`, uniquely determine the variable to use. These facets are
used to look up the variable in the CMOR table for the project.
Compliance with the variable definition from the CMOR table is checked when data is
loaded, to avoid unexpected results or errors during data processing. The strictness
of these checks can be [configured](../develop/fixing_data.html.md#cmor-check-strictness).
For example, the facets `project: CMIP6, mip: Amon, short_name: tas`
define the near-surface air temperature variable in the CMIP6 Amon table:

```default
        "tas": {
            "frequency": "mon", 
            "modeling_realm": "atmos", 
            "standard_name": "air_temperature", 
            "units": "K", 
            "cell_methods": "area: time: mean", 
            "cell_measures": "area: areacella", 
            "long_name": "Near-Surface Air Temperature", 
            "comment": "near-surface (usually, 2 meter) air temperature", 
            "dimensions": "longitude latitude time height2m", 
            "out_name": "tas", 
            "type": "real", 
            "positive": "", 
            "valid_min": "", 
            "valid_max": "", 
            "ok_min_mean_abs": "", 
            "ok_max_mean_abs": ""
        }, 
```

In some cases the `short_name` (called `out_name` in the CMOR tables) of a
variable may differ from the name used as a key in the CMOR table.
This is always the case for CMIP7, where the
[branded variable name](https://wcrp-cmip.github.io/cmip7-guidance/docs/CMIP7/Branded_Variables/)
is used, which is composed of the `short_name` followed
by an underscore and the `branding_suffix`. For example, the facets
`project: CMIP7, mip: atmos, short_name: tas, branding_suffix: tavg-h2m-hxy-u`
select one of the near-surface air temperature variables in the CMIP7 atmos table:

```default
        "tas_tavg-h2m-hxy-u": {
            "cell_measures": "",
            "cell_methods": "area: time: mean",
            "comment": "",
            "dimensions": [
                "longitude",
                "latitude",
                "time",
                "height2m"
            ],
            "long_name": "Near-Surface Air Temperature",
            "modeling_realm": "atmos",
            "out_name": "tas",
            "positive": "",
            "standard_name": "air_temperature",
            "units": "K"
        },
```

For other projects, the facet `branding_suffix` can also be used to distinguish
between variables from the same CMOR table that share the same `short_name`,
but differ in other aspects, even though these projects do not use branded variables.
For example, the `ch4Clim` entry in the CMIP6 Amon table can be selected in
the recipe by specifying `project: CMIP6, mip: Amon, short_name: ch4, branding_suffix: Clim`:

```default
        "ch4Clim": {
            "frequency": "monC", 
            "modeling_realm": "atmos atmosChem", 
            "standard_name": "mole_fraction_of_methane_in_air", 
            "units": "mol mol-1", 
            "cell_methods": "area: mean time: mean within years time: mean over years", 
            "cell_measures": "area: areacella", 
            "long_name": "Mole Fraction of CH4", 
            "comment": "Mole fraction is used in the construction mole_fraction_of_X_in_Y, where X is a material constituent of Y.", 
            "dimensions": "longitude latitude plev19 time2", 
            "out_name": "ch4", 
            "type": "real", 
            "positive": "", 
            "valid_min": "", 
            "valid_max": "", 
            "ok_min_mean_abs": "", 
            "ok_max_mean_abs": ""
        }, 
```