Classification of existing standard names for `units_metadata`

[JonathanGregory]

Dear all

Following the discussion in discuss issue cf-convention/vocabularies#125, conventions issue #481 was implemented in the latest CF release. This defines the new units_metadata attribute, which is strongly recommended to be provided for all variables with a units attribute that includes temperature units. It has three possible values.

units_metadata="temperature: on-scale" means that the temperature quantity is relative to the origin of the scale indicated by the units e.g. 10 degC means 10 Celsius degrees above freezing point, the zero of the Celsius scale.

units_metadata="temperature: difference" means that the temperature quantity is the difference between two temperatures, so the origin of the scale is irrelevant, and only the unit of measure matters e.g. 10 degC could be the difference between on-scale temperature of 20 degC and 30 degC, or equally between -40 degC and -30 degC.

This information is needed to convert the units correctly. For example, 10 degC on-scale equals 51 degF, but 10 degC difference equals 18 degF.

The third possibility, units_metadata="temperature: unknown", means that the data-writer doesn't know which it is. This is unsatisfactory, because the data-user has to decide what to do. That was of course the situation for all data written with previous versions of CF, and is still the situation if units_metadata is omitted.

As part of the discussion leading to this change, we decided that we would add some text to the description of every existing standard name that has temperature in its canonical units. This text will say in every case that it's strongly recommended to include the units_metadata attribute. There are three possible versions of the text we would add, depending on the quantity. Some standard names are for quantities that could only be on-scale; in those cases, the text will strongly recommend including units_metadata="temperature: on-scale". Some could only be a difference, and those will have units_metadata="temperature: difference" strongly recommended. Many could be either on-scale or difference. In those cases, the text will say that the appropriate value should be coded, depending on the data-writer's scientific understanding of the intention of the data.

In order to do this, we have to classify the existing standard names. @larsbarring and I have drafted a classification, which appears below, according to our scientific understanding of what these standard names might be used for. The names are grouped by their canonical unit. Comments and corrections are welcome. Note that "either" is a safe choice; it leaves the decision to the data-writer of whether the appropriate choice is in-situ or difference. Also note that for quantities which aren't pure temperature, "difference" means that the temperature part is interpreted as a difference. It doesn't mean the whole quantity is necessarily a difference between two values.

Once we've agreed this classification, we can proceed to draft the text to be added for each case. Of course, we will also have to do this for all future standard names that include temperature.

Best wishes

Jonathan

standard name	units_metadata
K
air_equivalent_potential_temperature	either
air_equivalent_temperature	either
air_potential_temperature	either
air_pseudo_equivalent_potential_temperature	either
air_pseudo_equivalent_temperature	either
air_temperature	either
air_temperature_anomaly	difference
air_temperature_at_cloud_top	either
air_temperature_at_effective_cloud_top_defined_by_infrared_radiation	either
air_temperature_threshold	on-scale
apparent_air_temperature	either
atmosphere_stability_k_index	either
atmosphere_stability_showalter_index	difference
atmosphere_stability_total_totals_index	difference
brightness_temperature	either
brightness_temperature_anomaly	difference
brightness_temperature_at_cloud_top	either
canopy_temperature	either
change_over_time_in_sea_water_conservative_temperature	difference
change_over_time_in_sea_water_potential_temperature	difference
change_over_time_in_sea_water_temperature	difference
dew_point_depression	difference
dew_point_temperature	either
difference_between_sea_surface_temperature_and_air_temperature	difference
dynamic_tropopause_potential_temperature	either
fire_temperature	either
freezing_temperature_of_sea_water	either
heat_index_of_air_temperature	either
land_ice_basal_temperature	either
land_ice_temperature	either
product_of_air_temperature_and_specific_humidity	either
sea_ice_basal_temperature	either
sea_ice_surface_temperature	either
sea_ice_temperature	either
sea_surface_foundation_temperature	either
sea_surface_skin_temperature	either
sea_surface_subskin_temperature	either
sea_surface_temperature	either
sea_water_conservative_temperature	either
sea_water_potential_temperature	either
sea_water_potential_temperature_at_sea_floor	either
sea_water_temperature	either
sea_water_temperature_anomaly	difference
sea_water_temperature_at_sea_floor	either
sea_water_temperature_difference	difference
soil_temperature	either
stagnation_temperature_in_air	either
surface_brightness_temperature	either
surface_temperature	either
surface_temperature_anomaly	difference
temperature_at_base_of_ice_sheet_model	either
temperature_at_top_of_ice_sheet_model	either
temperature_difference_between_ambient_air_and_air_lifted_adiabatically	difference
temperature_difference_between_ambient_air_and_air_lifted_adiabatically_from_the_surface	difference
temperature_in_ground	either
temperature_in_surface_snow	either
temperature_of_analysis_of_sea_water	either
temperature_of_sensor_for_oxygen_in_sea_water	either
toa_brightness_temperature	either
toa_brightness_temperature_assuming_clear_sky	either
toa_brightness_temperature_bias_at_standard_scene_due_to_intercalibration	difference
toa_brightness_temperature_of_standard_scene	either
tropical_cyclone_eye_brightness_temperature	either
tropopause_air_temperature	either
virtual_temperature	either
wet_bulb_potential_temperature	either
wet_bulb_temperature	either
wind_chill_of_air_temperature	either
K m-1
air_temperature_lapse_rate	difference
K m s-1
covariance_over_longitude_of_northward_wind_and_air_temperature	difference
product_of_eastward_sea_water_velocity_and_temperature	either
product_of_eastward_wind_and_air_temperature	either
product_of_northward_sea_water_velocity_and_temperature	either
product_of_northward_wind_and_air_temperature	either
product_of_upward_air_velocity_and_air_temperature	either
K m2 kg-1 s-1
ertel_potential_vorticity	difference
kg degree_C m-2
integral_wrt_depth_of_product_of_conservative_temperature_and_sea_water_density	either
integral_wrt_depth_of_product_of_potential_temperature_and_sea_water_density	either
K m
integral_wrt_depth_of_sea_water_temperature	either
K s
integral_wrt_time_of_air_temperature_deficit	difference
integral_wrt_time_of_air_temperature_excess	difference
degree_C
perceived_temperature	either
physiological_equivalent_temperature	either
sea_water_added_conservative_temperature	difference
sea_water_added_potential_temperature	difference
sea_water_redistributed_conservative_temperature	either
sea_water_redistributed_potential_temperature	either
universal_thermal_comfort_index	either
K Pa s-1
product_of_lagrangian_tendency_of_air_pressure_and_air_temperature	either
K s-1
ratio_of_sea_water_potential_temperature_anomaly_to_relaxation_timescale	difference
tendency_of_air_temperature	difference
tendency_of_air_temperature_due_to_advection	difference
tendency_of_air_temperature_due_to_boundary_layer_mixing	difference
tendency_of_air_temperature_due_to_convection	difference
tendency_of_air_temperature_due_to_diabatic_processes	difference
tendency_of_air_temperature_due_to_diffusion	difference
tendency_of_air_temperature_due_to_dissipation_of_nonorographic_gravity_waves	difference
tendency_of_air_temperature_due_to_dissipation_of_orographic_gravity_waves	difference
tendency_of_air_temperature_due_to_dry_convection	difference
tendency_of_air_temperature_due_to_longwave_heating	difference
tendency_of_air_temperature_due_to_longwave_heating_assuming_clear_sky	difference
tendency_of_air_temperature_due_to_longwave_heating_from_volcanic_ambient_aerosol_particles	difference
tendency_of_air_temperature_due_to_model_physics	difference
tendency_of_air_temperature_due_to_moist_convection	difference
tendency_of_air_temperature_due_to_radiative_heating	difference
tendency_of_air_temperature_due_to_shortwave_heating	difference
tendency_of_air_temperature_due_to_shortwave_heating_assuming_clear_sky	difference
tendency_of_air_temperature_due_to_shortwave_heating_from_volcanic_ambient_aerosol_particles	difference
tendency_of_air_temperature_due_to_stratiform_cloud_and_precipitation	difference
tendency_of_air_temperature_due_to_stratiform_cloud_and_precipitation_and_boundary_layer_mixing	difference
tendency_of_air_temperature_due_to_stratiform_precipitation	difference
tendency_of_air_temperature_due_to_turbulence	difference
tendency_of_sea_water_temperature	difference
tendency_of_sea_water_temperature_due_to_advection	difference
tendency_of_sea_water_temperature_due_to_horizontal_mixing	difference
tendency_of_sea_water_temperature_due_to_parameterized_eddy_advection	difference
tendency_of_sea_water_temperature_due_to_vertical_mixing	difference
J kg-1 K-1
soil_thermal_capacity	difference
specific_heat_capacity_of_frozen_ground	difference
specific_heat_capacity_of_sea_water	difference
W m-1 K-1
soil_thermal_conductivity	difference
thermal_conductivity_of_frozen_ground	difference
K2
square_of_air_temperature	either
square_of_sea_surface_temperature	either

[github-actions[bot]]

Thank you for your proposal. These terms will be added to the cfeditor (http://cfeditor.ceda.ac.uk/proposals/1) shortly. Your proposal will then be reviewed and commented on by the community and Standard Names moderator.

[davidhassell]

Dear @JonathanGregory and @larsbarring,

Thanks for putting this list together, and its clear preamble. Everything seems OK to me on a first look through. It was useful to check some of the full standard name definitions.

[efisher008]

Dear @JonathanGregory and @larsbarring,

I have added the broader text you suggested, i.e. _"It is strongly recommended to include a unitsmetadata attribute.", to the description of each standard name you listed in the CF editor. What do you think of including the additional text: "The value of this attribute should be "temperature: on-scale / temperature: difference"." for the names classified as on-scale / difference values respectively, and "The appropriate value of this attribute should be coded, depending on the scientific understanding of the intention of the data." when either value may be used?

I think we will just need to review individually each name to ensure that the classification is correct, although I'm sure both of you have already put a large amount of effort into selecting the units_metadata classifier. Thank you for your time on this.

Best regards, Ellie

[JonathanGregory]

Dear Ellie @efisher008

Thanks. That is sensible. For the cases which aren't "either", you could amalgamate the phrases i.e. _It is strongly recommended to include the attribute unitsmetadata="on-scale" or "difference" as the case may be. For all cases, but especially the "either" cases, it would help to refer to section 3.1.2 for an explanation of the meaning of the attribute.

Best wishes

Jonathan

[efisher008]

Hi @JonathanGregory,

Section 3.1.2 of the CF conventions includes the following text: _"In order to convert the units correctly, it is essential to know whether a temperature is on-scale or a difference. Therefore this standard strongly recommends that any variable whose units involve a temperature unit should also have a unitsmetadata attribute to make the distinction."

Would you suggest inserting this into the description for all value-types, or shortening it in some way?

Perhaps one of the sentences below could then be added for the cases which aren't either, depending on whether the value is "difference" or "on-scale"? _"unitsmetadata="temperature: on-scale" means that the temperature quantity is relative to the origin of the scale indicated by the units." or _"unitsmetadata="temperature: difference" means that the temperature quantity is the difference between two temperatures, so the origin of the scale is irrelevant, and only the unit of measure matters."

This would finally be followed in the description by _"It is strongly recommended to include the attribute [units_metadata/units_metadata="temperature: difference"/unitsmetadata="temperature: on-scale"]"

For example, the name air_temperature_anomaly would have the following description: _""anomaly" means difference from climatology. Air temperature is the bulk temperature of the air, not the surface (skin) temperature. In order to convert the units correctly, it is essential to know whether a temperature is on-scale or a difference. Therefore this standard strongly recommends that any variable whose units involve a temperature unit should also have a units_metadata attribute to make the distinction. units_metadata="temperature: difference" means that the temperature quantity is the difference between two temperatures, so the origin of the scale is irrelevant, and only the unit of measure matters. It is strongly recommended to include the attribute unitsmetadata="temperature: difference"."

Let me know what you think about this.

Best wishes, Ellie

[JonathanGregory]

Dear Ellie

Thanks for your suggestions. I think the words are fine, but we could be more concise. I would propose

For on-scale It is strongly recommended that a variable with this standard name should have the attribute units_metadata="temperature: on-scale", meaning that the temperature is relative to the origin of the scale indicated by the units, because it is essential to know whether a temperature is on-scale or a difference in order to convert the units correctly.

For difference It is strongly recommended that a variable with this standard name should have the attribute units_metadata="temperature: difference", meaning that it refers to temperature differences and implying that the origin of the temperature scale is irrelevant, because it is essential to know whether a temperature is on-scale or a difference in order to convert the units correctly.

For "either" It is strongly recommended that a variable with this standard name should have a units_metadata attribute, with one of the values "on-scale" or "difference", whichever is appropriate for the data, because it is essential to know whether the temperature is on-scale (meaning relative to the origin of the scale indicated by the units) or refers to temperature differences (implying that the origin of the temperature scale is irrevelant), in order to convert the units correctly.

Is that clear and sufficient, do you think - and others, such as @larsbarring?

Best wishes

Jonathan

[larsbarring]

@efisher008 and @JonathanGregory many thanks! I think the text suggested is clear and informative. But I wonder if it would be good to include a link to section 3.2.1 of the Conventions document. In particular for the case of "either" this would be helpful, because in this case the text (above) does not provide a definitive answer, but it is a small addition that would fit in the text for all three alternatives. E.g. something like:

" It is strongly recommended that a variable with this standard name should have the attribute units_metadata="temperature: ........." (cf. CF conventions section 3.2.1), ...... " Note that there are small variations to this text in the three alternatives.

[efisher008]

Hi @larsbarring and @JonathanGregory,

Thanks again for the comments, the more concise definitions seem sensible. Lars, I'm not sure if there is a precedent for including links to the CF conventions document in a standard name definition (the only example I can think of where there is an external link in a name is for area_type, which directs to the area type table and needs to be inserted by a 'make' command when pushing changes to the standard name table). Is this common? Perhaps @japamment could help answer this.

Best wishes, Ellie

[larsbarring]

Hi @efisher008 , You are right, while there are many web links in the descriptions none points to the conventions text. I think that it would be helpful to provide this link, in particular as we are introducing a new concept. On the other hand, the actual link https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#temperature-units is rather awkward to put in the text.

[sethmcg]

We could use a link shortener. tinyurl.com is free and allows customization, so the link could be something like tinyurl.com/cf-tunits

[JonathanGregory]

Dear all

I favour https://cfconventions.org/cf-conventions/cf-conventions.html#temperature-units. I think that citing the working version (rather than 1.11) and the URL (rather than giving the section number) are preferable because they are more future-proof. I agree that a tinyurl would be a neat way to make it shorter, but it's also less transparent. If it's important to have a shorter URL, we could create a special page copying the relevant part of the convention e.g. at https://cfconventions.org/temperature-units.html, but that would require maintenance.

Best wishes

Jonathan

[larsbarring]

Yes, indeed, this link is much better. While it is a bit long I think that it is acceptable, and only marginally longer that the currently longest one, which I believe is "http://glossary.ametsoc.org/wiki/Pseudoequivalent_potential_temperature"

[efisher008]

Hello @JonathanGregory,

I agree with your conclusion and it sounds as though there is an agreement about the link format (https://cfconventions.org/cf-conventions/cf-conventions.html#temperature-units). I will update the descriptions of each name with the concise definitions for each value and add the link at the end.

Best wishes, Ellie

[JonathanGregory]

Thanks, Ellie.

[efisher008]

Hi @JonathanGregory,

I've made the changes to the description of these names, and following advice from @japamment I am now adding proposal information in the CF editor (where I can find this) from the original issues. Once the information has been updated the names will be accepted with their term changes. Thanks again.

Best wishes, Ellie

[efisher008]

Hi @JonathanGregory and @larsbarring ,

I have added the proposal details to all names in this issue and have now accepted 123 of the 124 names included (the exception is freezing_temperature_of_sea_water, which is missing a description of the term and I think this should be agreed before it is accepted). Thank you for yours and Lars' detailed work on advising the units_metadata attribute and associated text for the description.

Best, Ellie

[efisher008]

Closing this issue as these names have been accepted in version 85 of the CF standard names table, published on 21 May 2024 (https://cfconventions.org/Data/cf-standard-names/85/build/cf-standard-name-table.html).