Consistency between DR variables, branded variables, and CMOR tables

[JamesAnstey]

With the release of the first official version of the CMIP7 CMOR tables, generated from DR v1.2.2.2:
https://github.com/WCRP-CMIP/cmip7-cmor-tables/releases/tag/DR-1.2.2.2-v1.0.0
DR variables sharing the same branded variable are mostly consistent now, but there are a few outstanding things, so I'm opening this issue to keep track of them.

First, it's worth saying that these earlier issues in this repo:
#176
#155
#143
are related but now somewhat out of date or obsolete because the VR implementation is paused for the moment, so I think it's simpler to close these and start a new issue (we can reopen any if needed).

List of outstanding things, and thanks @matthew-mizielinski for keeping track of these when generating the CMOR tables:

• long_name (in the DR Variables table this is the "Title" column):

  • update long names in DR for consistency, based on https://github.com/WCRP-CMIP/cmip7-cmor-tables/blob/main/reference/dr_v1.2.2.2_long_name_overrides.json

• realm:

  • update realms in DR for consistency, based on https://github.com/WCRP-CMIP/cmip7-cmor-tables/blob/main/reference/dr_v1.2.2.2_realm_overrides.json
  • look at moving some of the global versions of landIce variables from atmos into landIce as their primary realm to minimise duplication.

• cell_measures:

  • globally replace "::OPT" with "--OPT" and "::MODEL" with "--MODEL" in cell_measures as CMOR understands these
  • if possible also change cell_measures in the landIce variables to be consistent between the GLB, ATA and GRL versions. (this would allow us to reintroduce cell_measures into the tables themselves if we chose to do so)

• comment (in the DR Variables table this is the "Description" column):

  • do we have the time/energy to make comments consistent?
  • noting comment ("Description") provides useful info, but so also does "Processing Note" and users would find that in the DR, not the CMOR tables

[JamesAnstey]

• update realms in DR for consistency, based on https://github.com/WCRP-CMIP/cmip7-cmor-tables/blob/main/reference/dr_v1.2.2.2_realm_overrides.json
• look at moving some of the global versions of landIce variables from atmos into landIce as their primary realm to minimise duplication.

Based on the attached comparison (json file) I found these overrides would make realms consistent across DR variables sharing the same branded variable name (i.e., fix the few inconsistencies - most DR variables are already consistent):

{
  "aerosol.sfpm25.tavg-h2m-hxy-u.1hr.GLB": "aerosol atmosChem",
  "landIce.snc.tavg-u-hxy-is.mon.ATA": "landIce land",
  "landIce.snc.tavg-u-hxy-is.mon.GLB": "landIce land",
  "landIce.snc.tavg-u-hxy-is.yr.ATA": "landIce land",
  "landIce.snm.tavg-u-hxy-is.mon.GLB": "landIce land",
  "landIce.tsn.tavg-u-hxy-is.mon.GLB": "landIce land",
  "ocean.sfdsi.tavg-u-hxy-sea.3hr.GLB": "ocean seaIce",

  "landIce.hfls.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.hfss.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.orog.tavg-u-hxy-is.mon.GLB": "land",
  "landIce.prra.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.prsn.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.rlds.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.rlus.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.rsds.tavg-u-hxy-is.mon.GLB": "atmos land",
  "landIce.rsus.tavg-u-hxy-is.mon.GLB": "atmos land landIce",
  "landIce.ts.tavg-u-hxy-is.mon.GLB": "atmos land landIce"
}

The first group are already in the realm overrides json file, the second group are additional ones I found would be needed. Primary realm = first realm in list.

In all these cases, the above suggestion for realm is motivated by the realm of other DR variables using the same physical parameter / root name. E.g., other prra DR variables have atmos as the primary realm.

[JamesAnstey]

@martinjuckes @chloemackallah @bethdingley Following our discussion in the DR co-leads meeting today, here's a comparison of current values and proposed changes for long_name and realm:

realm_old2new.json

long_name_old2new.json

Each file gives the attribute value in v1.2.2.2 and the proposed change. The motivation is to make these DR variables have the same long name or realm as other DR variables that share the same branded name, enabling CMOR tables generated from the DR to be keyed by branded variable name. Comments on any of these proposed changes are welcome.

For realm, my understanding is that it's assigned based on the physical processes a variable is related to, for example as stated in the EMD, p. 7, and in the DR Airtable I found the definition of realm:

A string that indicates the high level modeling component which is particularly relevant. Note that sometimes a variable will be equally (or almost equally relevant) to two or more realms, in which case a primary realm is assigned as the first listed and other relevant realms follow in a space separated list.

Given this, it seems logical to me that these variables should have the same realm(s) as other DR variables that use the same physical parameter. Does that sound reasonable?

In case anyone wants to see more detail, these files have the full results of my comparison of DR variables sharing the same branded variable names:

realm.json

long_name.json

Each of these files has a "Comparison" dict keyed by branded variable name, listing the DR variables sharing that branded variable name and the attribute with differences (as well as other attributes for context: frequency, region, and cmip6/7 compound names). In each of these groups, there's a DR variable that's the odd one out, i.e. it has a value for the attribute (e.g. realm) that doesn't agree with the others. These files are produced with this script, for example:

./compare_branded_variables.py ../examples/variables_v1.2.2.2_cmip7names.json out.json

(Of course the same info could be viewed in Airtable by filtering on branded variable name.)

All the above applies to a relatively small number of the 1974 DR variables / 1431 branded variables in the DR. If the proposed updates to long name & realm are applied and compare_branded_variables.py is run comparing all CMOR table attributes except comment and cell_measures, i.e. in its input yaml file I put:

compare_attributes:
- cell_methods
- dimensions
- long_name
- modeling_realm
- out_name
- positive
- standard_name
- units

then all DR variables sharing the same branded variable name have the same values for the above attributes (i.e., they are consistent in this sense).

Running the same check for just cell_measures finds only 24 branded variables with differences. There are a lot more for comment (Description in Airtable), 156 branded variables affected. For completeness here are the comparison files for those checks too:

cell_measures.json

comment.json

[martinjuckes]

Realm changes: these changes would introduce more inconsistencies into the request. Why are they needed?

If the majority of variables with realm landIce retain that realm, why is the variable registry unable to comply with the data request realm in the handful of cases presented? People use metadata to organise and group variables. Making apparently random changes to a handful of variables will break up existing structures. If there are reasons for these suggestions, beyond the fact that something different has been entered into the variable registry by some mechanism which clearly contravenes our agreed procedures, it would be helpful to know.

[mpmoine]

Hi @JamesAnstey, many thanks for this in-deep analysis and proposed revisions for realm and long_name.

I (almost 😉 ) agree with your logic of the 2 bijective relationships:

• long_name <-> branded_name (but sometimes the realm or the region - that's not part of the brand- influence the long_name(*) )
• realm <-> physical_parameter

(*) f.e. :

• landIce.prra.tavg-u-hxy-is.mon.GLB => long_name="Rainfall Flux over Land Ice"
• atmos.prra.tavg-u-hxy-lnd.day.GLB => long_name="Rainfall Flux over Land"
• atmos.prra.tavg-u-hxy-is.mon.GRL => long_name="Rainfall Flux over Land Ice"

I went through your list of proposed changes for long_names, compared with the one we had in the CMIP6 DR and agree with 95% of them 👍

I have suggestions only for 4 of them:

  "atmos.cltmodis.tavg-u-hxy-u.mon.GLB": {
    "cmip6_compound_name": "Emon.cltmodis",
    "long_name (v1.2.2.2)": "MODIS Total Cloud Cover Percentage",
    "long_name (proposed)": "MODIS Total Cloud Area Percentage"
  },

--> I would rather keep "Cover". I undestantdyou choose to align on the CF standard name but all the other cloud simulator products (ISCCP, CALIPSO) have "Cover" in their long_names, only MODIS has one variable ('CMIP6 compound name' = CFmon.cltmodisSouth30) having "Area" instead (see screenshot)

"land.evspsblsoi.tavg-u-hxy-u.day.GLB": {
    "cmip6_compound_name": "Eday.evspsblsoi",
    "long_name (v1.2.2.2)": "Daily water evaporation flux from soil",
    "long_name (proposed)": "Water evaporation from soil"
  },

--> you forgot the first letter in upper-case --> "Water Evaporation from Soil"

  "land.evspsblveg.tavg-u-hxy-u.3hr.GLB": {
    "cmip6_compound_name": "3hr.evspsblveg",
    "long_name (v1.2.2.2)": "Evaporation from canopy",
    "long_name (proposed)": "Water evaporation from canopy"
  },

--> you forgot the first letter in upper-case --> "Water Evaporation from Canopy"

  "land.evspsblveg.tavg-u-hxy-u.day.GLB": {
    "cmip6_compound_name": "Eday.evspsblveg",
    "long_name (v1.2.2.2)": "Daily water evaporation flux from canopy",
    "long_name (proposed)": "Water evaporation from canopy"
  },

--> you forgot the first letter in upper-case --> "Water Evaporation from Canopy"

[mpmoine]

Sorry, another one:

I agree with your proposition for LImon.snicefreezIs

  "landIce.snrefr.tavg-u-hxy-is.mon.GLB": {
    "cmip6_compound_name": "LImon.snicefreezIs",
    "long_name (v1.2.2.2)": "Ice Sheet Surface Snow and Ice Refreeze Flux",
    "long_name (proposed)": "Surface Snow and Ice Refreeze Flux"
  },

--> but I think that we should change, in the same way, long_name of Eday.snrefr (not in your json) from "Refreezing of Water in the Snow" to "Surface Snow and Ice Refreeze Flux" for consistency (see snapshot - not visible : all the variables of this snapshot share the same var_rootname=snrefr)

[mpmoine]

... And I suspect there is still other long_name inconsistency to solve.

Taking var_rootname=prra sounds like LImon.prrals and SImon.sipr (line 7 and 8 respectively of the attached screenshot - all the variables in this screenshot share the same var_rootname=prra) need to have there long_names changed:

• LImon.prrals : IceSheet Rainfall Rate => Rainfall Flux over Land Ice
• SImon.sipr: Rainfall rate over Sea Ice => Rainfall Flux over Sea Ice

[mpmoine]

To answer your question @JamesAnstey :

comment -> do we have the time/energy to make comments consistent?

I would say no, no time/energy for that (perfection is unattainable and we must live with that 😉)

[martinjuckes]

Hello All,

It has taken me some time to work out what is going on here. I'm afraid I think the changes being suggested are a very bad idea and will both create and ambiguity and harm consistency in the data request.

Long names

The long names are, clearly, a form of name. During CMIP6 there a considerable effort was made to ensure that they were all distinct. Having different names for different quantities has obvious benefits.

I cannot see the benefits of revising names so that multiple quantities in the data request share the same name. They have different names for clear reasons.

The names are already in use, e.g. in the GMD papers describing the data request, and may also be in use in modeling centres using published versions of the data request.

Realms

Again, different quantities have different lists of realms for reasons. The suggested changes are clearly introducing inconsistency.

The definition of the branded variables is such that a single branded variable is associated with a range of variables that have different realms. That does not mean there is an error anywhere, it is just an objective consequence of the branded variable definition that we need to work with.

[sol1105]

Variables in the data request that share the branded variable name should share the long_name, realm and possibly other attributes. That variables are organized into CMOR tables by their realm is completely arbitrary: there could be a single CMIP7.json as CMOR table as well, so we cannot have the same variables (i.e. branded variables) with different realm or long_name, etc. attributes (they would be duplicates).

Variables that only share the same root name however, can differ in these attributes.

For example:

• landIce.ts.tavg-u-hxy-is.mon.GLB
• land.ts.tavg-u-hxy-land.mon.GLB

These variables can differ in their realm and other attributes, but if there was a land.ts.tavg-u-hxy-is.3hr.GLB, the realm, etc. would have to be made consistent between this variable and landIce.ts.tavg-u-hxy-is.mon.GLB.

I did not look at it in full detail, but in the suggested realm changes it looks like also variables with differing branded variable name that only share the same root name would get consistent realms (and possibly other attributes), which is not required and potentially introduces issues in the variable definitions.

[martinjuckes]

@sol1105 I believe your statement about different variables having the same name is incorrect and unworkable.

It is a substantial change on past practise and I can't see any evidence that anyone has thought about the impact of such a change.

The same goes for the realm.

[sol1105]

@martinjuckes I think there is a misunderstanding. My statement only applies to variables sharing the same branded variable name (like ts.tavg-u-hxy-land). A branded variable is unique by definition, so when variables share the same branded variable name, they are the exact same variable and must be consistent in realm, long_name, and other defining attributes. In terms of the data request, those variables can differ in requested frequency, region and grid (eg. native, 1deg, ...) only.

Variables that only share the root name (like ts) represent the same physical parameter but are (somewhat) distinct and can differ in realm, long_name, and other attributes.

[martinjuckes]

@sol1105 No misunderstanding. I think that what you are suggesting is incorrect and unworkable, but thanks for setting out the context which does make the thinking behind it clearer.

A branded variable is defined by the branding algorithm, data request variables have been defined by a consultation process. A branded variable is obviously unique in a sense, but can be used to by several different data request variables. There are multiple reasons why these may have different long names and realms.

I take your statement "when variables share the same branded variable name, they are the exact same variable and must be consistent in realm, long_name" as a statement of intent. It is clearly not true at the moment. Personally, I don't think it can ever really work, but we obviously can't rule out that possibility. For now, however, it has been introduced far to late for an in depth discussion.

The branding algorithm maps a range of different quantities onto the same branding. It is simply not true to say that different quantities mapping onto the same branding are exactly the same.