Update standard name rules with rules for units

[climbfuji]

Add a section about rules for variables to the standard name rules. In particular, provide guidance for dimensionless variables.

Disclaimer. I created this PR on GitHub without actually rendering the rst file.

See #19 and NCAR/ccpp-framework#397 for discussions related to this PR.

[climbfuji]

@ligiabernardet @dudhia I just invited you as collaborators for CCPPStandardNames so that I can add you as reviewers. In the meantime, please see this PR for a proposed extension of the standard name rules regarding units.

[cacraigucar]

This is very clear and a welcome addition to the StandardNames

[dudhia]

should be m3 m-3 - seems OK otherwise

[climbfuji]

Apologies, stupid mistake. Should be fixed now. Please approve if satisfied. Thanks!

[dudhia]

this looks fine now

[dudhia]

With this new index definition, will the previous real 'index' types be corrected in the standard names file? Will there be a new category unit that should be added here?

…

On Mon, Aug 23, 2021 at 10:13 AM Dom Heinzeller ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In StandardNamesRules.rst <#21 (comment)> : > + conventions <https://cfconventions.org/standard-names.html>`, the units should + be identical to the canonical units listed there + +#. For variables without an existing match in the CF conventions, the units should + follow the International System of Units (SI/metric system), see https://www.nist.gov/pml/weights-and-measures/metric-si/si-units + +#. For dimensionless variables, the following units can be used: + ++------------------------+-------------------------------------------------------------------------------------+ +| **Unit** | **Use case** | ++========================+=====================================================================================+ +| count | integers that describe the dimension/length of an array | +| flag | logicals/booleans that can be either true or false | +| index | integers that can be an index in an array | +| kg kg-1 | mass mixing ratios | +| m m-3 | volumetric mixing ratios (e.g. for soil moisture) | Apologies, stupid mistake. Should be fixed now. Please approve if satisfied. Thanks! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#21 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEIZ77DH4VK5VAB2VYOMF6DT6JXSRANCNFSM5CUXMKKQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .

[climbfuji]

With this new index definition, will the previous real 'index' types be corrected in the standard names file? Will there be a new category unit that should be added here?
…

The way I understood our previous conversations was that we accepted there are issues with these reals, and we (... well, me) are going to fix this as soon as possible. In the meantime, we chose to "ignore".

[dudhia]

OK, need to remember later.

…

On Mon, Aug 23, 2021 at 10:28 AM Dom Heinzeller ***@***.***> wrote: With this new index definition, will the previous real 'index' types be corrected in the standard names file? Will there be a new category unit that should be added here? … <#m_4828087149077020963_> The way I understood our previous conversations was that we accepted there are issues with these reals, and we (... well, me) are going to fix this as soon as possible. In the meantime, we chose to "ignore". — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#21 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEIZ77G5QNHIWRZBM4D332LT6JZMPANCNFSM5CUXMKKQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .

[ligiabernardet]

Thank you for this effort in clarifying the units, especially the dimensionless ones.

[ligiabernardet]

The table is not rendered correctly. Please use other tables as a template, and note that there must be a dashed line between each lines of the table.

[climbfuji]

Thanks, should be ok now. I rendered it on my mac using rst2html.py StandardNamesRules.rst > StandardNamesRules.html and the results looked ok.

[dudhia]

Good point. Soil moisture is m3 m-3 but not a volumetric mixing ratio, instead a volumetric fraction. Mixing ratio makes no sense in this context (sorry I think I confused this issue above).

…

On Mon, Aug 23, 2021 at 7:48 PM ligiabernardet ***@***.***> wrote: ***@***.**** requested changes on this pull request. Thank you for this effort in clarifying the units, especially the dimensionless ones. ------------------------------ In StandardNamesRules.rst <#21 (comment)> : > +Units +===== + +#. For variables with an existing match in the `Climate and Forecast (CF) metadata + conventions <https://cfconventions.org/standard-names.html>`, the units should + be identical to the canonical units listed there + +#. For variables without an existing match in the CF conventions, the units should + follow the International System of Units (SI/metric system), see https://www.nist.gov/pml/weights-and-measures/metric-si/si-units + +#. For dimensionless variables, the following units can be used: + ++------------------------+-------------------------------------------------------------------------------------+ +| **Unit** | **Use case** | ++========================+=====================================================================================+ +| count | integers that describe the dimension/length of an array | The table is not rendered correctly. Please use other tables as a template, and note that there must be a dashed line between each lines of the table. ------------------------------ In StandardNamesRules.rst <#21 (comment)> : > + conventions <https://cfconventions.org/standard-names.html>`, the units should + be identical to the canonical units listed there + +#. For variables without an existing match in the CF conventions, the units should + follow the International System of Units (SI/metric system), see https://www.nist.gov/pml/weights-and-measures/metric-si/si-units + +#. For dimensionless variables, the following units can be used: + ++------------------------+-------------------------------------------------------------------------------------+ +| **Unit** | **Use case** | ++========================+=====================================================================================+ +| count | integers that describe the dimension/length of an array | +| flag | logicals/booleans that can be either true or false | +| index | integers that can be an index in an array | +| kg kg-1 | mass mixing ratios | +| m3 m-3 | volumetric mixing ratios (e.g. for soil moisture) | This is at odds with rule number 7 listed above, which says: *When referring to soil quantities, volume_fraction should be used to express the volumetric soil moisture.* ⬇️ Suggested change -| m3 m-3 | volumetric mixing ratios (e.g. for soil moisture) | +| m3 m-3 | volume fraction (e.g. for soil moisture) | — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#21 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEIZ77CUM67AH5IEYZY2MNDT6L27TANCNFSM5CUXMKKQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .