Second rules update in v1 branch, update names, update `write_standard_name_table.py` to allow for subsections #87

mkavulich · 2024-12-13T03:41:07Z

This is the second round of proposed rules changes based on our ongoing discussion to make both rules and names as consistent as possible. Major updates include:

Standard Names

New "base_names" section, with subsections
Convert instances of "surface_X" to "X_at_surface"
Convert some instances of "air_X" or "X_of_air"
Explicitly state what mass mixing ratios are with respect to in long_name
Convert "mixing_ratio" to "water_vapor_mixing_ratio_wrt_moist_air"
Convert "surface_albedo" to simply "albedo", "surface_roughness_length" to simply "roughness_length"

Rules

Update construction template to include [non-instant time] and [non-current time], swap [at level] and [in medium]
More detailed description of transformations and how they can work on multiple base names
Add a few more transformations

`write_standard_name_table.py`

Updated to allow sub-sections in the standard names list

You can see these changes in the form of a Google doc for better visualization here: https://docs.google.com/document/d/19ysUCWDhv53W8fQbElW7opr_1Pm7ck95QRUyKM_qy4E/edit?tab=t.0

Note: with this update, we have 347 standard names that are fully compliant with the rules we have set out. A big portion of the remainder are "flag"-type variables, indices, etc, which are not fully accounted for in the rules yet.

…xner_function --> exner_function, add long names where appropriate

…rd names (keep in long names for reference), slightly revise rules on the proper term to align with other uses of "mixing ratio"

… subsections

climbfuji · 2024-12-13T21:38:34Z

StandardNamesRules.rst


   This construction was originally based on rules set forth in the
   `CF guidelines <http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html>`_),
   but have since evolved for better consistency and generality across a broader set of fields
   than was originally envisioned by the CF conventions. "``medium``" should be specified when
-   the variable in question is a substance or other quantity contained within some other medium
-   (e.g. for "mole_fraction_of_ozone_in_air", the base name is "ozone", while the medium is "air"). 
+   the variable in question is a substance or other quantity contained within some other the medium


The added "the" doesn't make sense here

climbfuji · 2024-12-13T21:40:38Z

StandardNamesRules.rst

@@ -429,13 +446,13 @@ Special phrases
 +------------------------+-------------------------------------------------------------------------------------+
 |frozen_water            | ice                                                                                 |
 +------------------------+-------------------------------------------------------------------------------------+
-| longwave               | longwave radiation                                                                  |
+| longwave               | Longwave radiation. Defined as thermal emission of EM radiation from the planet.    |


I'd either spell out electromagnetic or drop EM altogether

climbfuji · 2024-12-13T21:40:43Z

StandardNamesRules.rst

 +------------------------+-------------------------------------------------------------------------------------+
 | moisture               | water in all phases contained in soil                                               |
 +------------------------+-------------------------------------------------------------------------------------+
 | ocean                  | used instead of in_sea_water for quantities which are large-scale rather than local |
 +------------------------+-------------------------------------------------------------------------------------+
-| shortwave              | shortwave radiation                                                                 |
+| shortwave              | Shortwave radiation. Defined as EM emissions from the sun                           |


climbfuji · 2024-12-13T23:21:25Z

standard_names.xml

+                     long_name="coefficient">
+        <type units="1">real</type>
+      </standard_name>
+      <standard_name name="coefficient"


Duplicate of line 26-29

climbfuji · 2024-12-13T23:22:39Z

standard_names.xml

+                     long_name="Molecular oxygen, O₂">
+      </standard_name>
+      <standard_name name="ozone"
+                     long_name="Ozone, O₃">


Will these non-ASCII characters work? (also line 246)

climbfuji · 2024-12-13T23:24:34Z

standard_names.xml

@@ -2311,7 +2831,8 @@
      <standard_name name="upward_virtual_potential_temperature_flux">
         <type kind="kind_phys" units="K m s-1">real</type>
      </standard_name>
-      <standard_name name="surface_upward_specific_humidity_flux_for_mellor_yamada_janjic_surface_layer_scheme">
+      <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_mellor_yamada_janjic_surface_layer_scheme"


We should probably define MYJ as the abbreviation to use in the standard name, and the full name in the long name? Like PBL and GWD in my open PR?

climbfuji · 2024-12-13T23:25:04Z

standard_names.xml

         <type kind="kind_phys" units="Pa">real</type>
      </standard_name>
      <standard_name name="control_for_surface_layer_evaporation">
         <type kind="kind_phys" units="1">real</type>
      </standard_name>
-      <standard_name name="surface_specific_humidity_for_myj_schemes">
+      <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes"


Here, MYJ should be uppercase in the standard name, and spelled out in the long name

Rule 17 says names are insensitive, does it matter here?
If so, maybe we should add something and uppercase the abbreviations in the Acronyms, Abbreviations, and Aliases section? Or is it just for initials of names?

That (rule 17) is a good point I completely forgot about. I like consistency and would prefer either lowercase or uppercase. We can talk about it at one of the next meetings, if the majority thinks that case insensitive is fine, then I can live with that, too.

climbfuji · 2024-12-13T23:26:45Z

standard_names.xml

         <type kind="kind_phys" units="fraction">real</type>
      </standard_name>
      <standard_name name="lwe_surface_snow_from_coupled_process">
         <type kind="kind_phys" units="m">real</type>
      </standard_name>
-      <standard_name name="surface_upward_latent_heat_flux_from_coupled_process">
+      <standard_name name="upward_latent_heat_flux_at_surface_from_coupled_process">


What is the difference between for_coupling and from_coupled_process (not for vs from, but coupling vs coupled process)?

gold2718

Great (and great big) piece of work!
A few requested changes and a lot of questions along with a few suggestions.
Also, should all long names begin with an capitalized word? Right now, there is a mix.

gold2718 · 2024-12-26T15:00:28Z

tools/write_standard_name_table.py

+        for std_name in sec:
+            if std_name.tag == 'section':
+                parse_section(snl, std_name, level + '#')
+                continue


Why use continue instead of a regular else clause?

gold2718 · 2024-12-26T19:04:16Z

standard_names.xml

+                      more specific standard names.\n">
+      <standard_name name="amount"
+                     long_name="amount">
+        <type units="kg m-2">real</type>


What is the role of specific units here? Can't the units be different in the full standard name, or more precisely, in a variable with the standard name? Do we need the units in this section?

gold2718 · 2024-12-26T22:28:02Z

standard_names.xml

+      <standard_name name="air_temperature/water_vapor"
+                     long_name="air_temperature/water_vapor">
+      </standard_name>


This is not a legal standard name (rule 16) and the long name is not helping me understand what it is.

gold2718 · 2024-12-26T22:30:22Z

standard_names.xml

+                      also be considered standard names on their own. See the\n
+                      full list of standard names for further details.\n">
+      <standard_name name="absolute_vorticity"
+                     long_name="absolute_vorticity">


The long names here and below are supposed to be descriptive and do not need the underscores. If you are just going to copy the standard name, please omit the long name.

gold2718 · 2024-12-26T22:33:01Z

standard_names.xml

+      <standard_name name="water"
+                     long_name="water">
+      </standard_name>


What is this? How is it related to all the other water variables?

gold2718 · 2024-12-31T15:14:47Z

standard_names.xml

@@ -2431,7 +2962,8 @@
      <standard_name name="weight_for_potential_temperature_at_top_of_viscous_sublayer">
         <type kind="kind_phys" units="1">real</type>
      </standard_name>
-      <standard_name name="weight_for_specific_humidity_at_top_of_viscous_sublayer">
+      <standard_name name="weight_for_water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer"
+                   long_name="Weight for specific humidity (water vapor mass mixing ratio with respect to moist air) at the top of the viscous sublayer">


Is this "weight" as in "weighting factor"? If so, could "weighting factor" be used in the long name? If not, why are the units "1"?

gold2718 · 2025-01-01T11:05:28Z

standard_names.xml

@@ -2589,16 +3125,20 @@
      <standard_name name="max_vegetation_area_fraction">
         <type kind="kind_phys" units="fraction">real</type>
      </standard_name>
-      <standard_name name="nir_albedo_strong_cosz">
+      <standard_name name="nir_albedo_strong_cosz"


Does cosz need to be in the Acronyms, Abbreviations, and Aliases section?

gold2718 · 2025-01-01T13:00:02Z

standard_names.xml

+      <standard_name name="direct_uv_and_vis_shortwave_flux"
+                     long_name="direct_uv_and_vis_shortwave_flux">
+      </standard_name>
+      <standard_name name="direct_visible_albedo"


Is there a reason there are some uses of visible instead of vis?

gold2718 · 2025-01-01T17:05:18Z

standard_names.xml

         <type kind="kind_phys" units="J m-2">real</type>
      </standard_name>
-      <standard_name name="cumulative_surface_downwelling_diffuse_uv_and_vis_shortwave_flux_for_coupling_multiplied_by_timestep">
+      <standard_name name="cumulative_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep">


I think it would be helpful to spell out uv_and_vis_shortwave in a long name:

Suggested change

<standard_name name="cumulative_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep">

<standard_name name="cumulative_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep"

long_name="Cumulative downwelling diffuse ultraviolet_and_visible parts of the shortwave flux at surface for coupling multiplied by timestep">

This suggestion also applies to other uses of uv_and_vis_shortwave.

gold2718 · 2025-01-01T17:10:27Z

standard_names.xml

         <type kind="kind_phys" units="J m-2">real</type>
      </standard_name>
-      <standard_name name="cumulative_surface_downwelling_direct_nir_shortwave_flux_for_coupling_multiplied_by_timestep">
+      <standard_name name="cumulative_downwelling_direct_nir_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep">


I think it would be helpful to spell out nir_shortwave in a long name:

Suggested change

<standard_name name="cumulative_downwelling_direct_nir_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep">

<standard_name name="cumulative_downwelling_direct_nir_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep"

long_name="Cumulative downwelling direct near infrared portions shortwave flux at surface for coupling multiplied by timestep">

This suggestion also applies to other uses of `nir_shortwave,

mkavulich added 16 commits December 12, 2024 17:03

First round of rules updates, mostly discussed at the last meeting

8298ff0

Fix image embedding

6746dba

Fix some links

999c887

minor updates

34f9b03

Fix spelling in standard names

c8f4202

Rename surface_roughness_length --> roughness_length, dimensionless_e…

0b2c439

…xner_function --> exner_function, add long names where appropriate

Update albedo standard names

d66db49

Some more renames: surface_* to *_at_surface, air_* to *_of_air

b47546c

Updates involving specific humidity: remove use of the term in standa…

c4c2600

…rd names (keep in long names for reference), slightly revise rules on the proper term to align with other uses of "mixing ratio"

Add long name descriptions to mass mixing ratios as specified in rules

2d7cfbf

A bunch more surface_x --> x_at_surface

66f61aa

re-factor logic in write_standard_name_table.py so that it can handle…

c3c321e

… subsections

Add first round of base names

9ab244b

Remaining Rules updates from Google Doc

1181782

Add rest of "base names" section

8760c33

Fix format

c1a4dd5

mkavulich requested review from cacraigucar, climbfuji, dustinswales, gold2718, grantfirl, mattldawson, mwaxmonsky, nusbaume, peverwhee, svahl991, MayeulDestouches and ss421 as code owners December 13, 2024 03:41

climbfuji reviewed Dec 13, 2024

View reviewed changes

gold2718 requested changes Jan 1, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Second rules update in v1 branch, update names, update `write_standard_name_table.py` to allow for subsections #87

Second rules update in v1 branch, update names, update `write_standard_name_table.py` to allow for subsections #87

mkavulich commented Dec 13, 2024

climbfuji Dec 13, 2024

climbfuji Dec 13, 2024

climbfuji Dec 13, 2024

climbfuji Dec 13, 2024

climbfuji Dec 13, 2024

climbfuji Dec 13, 2024

climbfuji Dec 13, 2024

gold2718 Dec 25, 2024

climbfuji Dec 26, 2024

climbfuji Dec 13, 2024

gold2718 left a comment

gold2718 Dec 26, 2024

gold2718 Dec 26, 2024

gold2718 Dec 26, 2024

gold2718 Dec 26, 2024

gold2718 Dec 26, 2024

gold2718 Dec 31, 2024

gold2718 Jan 1, 2025

gold2718 Jan 1, 2025

gold2718 Jan 1, 2025

gold2718 Jan 1, 2025

	<standard_name name="cumulative_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep">
	<standard_name name="cumulative_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep"
	long_name="Cumulative downwelling diffuse ultraviolet_and_visible parts of the shortwave flux at surface for coupling multiplied by timestep">

	<standard_name name="cumulative_downwelling_direct_nir_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep">
	<standard_name name="cumulative_downwelling_direct_nir_shortwave_flux_at_surface_for_coupling_multiplied_by_timestep"
	long_name="Cumulative downwelling direct near infrared portions shortwave flux at surface for coupling multiplied by timestep">

Second rules update in v1 branch, update names, update write_standard_name_table.py to allow for subsections #87

Are you sure you want to change the base?

Second rules update in v1 branch, update names, update write_standard_name_table.py to allow for subsections #87

Conversation

mkavulich commented Dec 13, 2024

Standard Names

Rules

write_standard_name_table.py

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gold2718 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Second rules update in v1 branch, update names, update `write_standard_name_table.py` to allow for subsections #87

Second rules update in v1 branch, update names, update `write_standard_name_table.py` to allow for subsections #87

`write_standard_name_table.py`