[release/v1] Fourth major update in v1 branch: Rename long_name --> description, expand list of abbreviations, update descriptions
#116
Conversation
… to long_name entries
…dard_name_table.py and rules for the renaming. Also make some fixes and updates to these new descriptions.
mkavulich
requested review from
MayeulDestouches,
cacraigucar,
climbfuji,
dustinswales,
gold2718,
grantfirl,
mattldawson,
mwaxmonsky,
nusbaume,
peverwhee,
ss421 and
svahl991
as code owners
| that represents the variable name, and (optionally) a "long_name" attribute that gives | ||
| a detailed description of what that name represents. The standard_name XML entry also contains a nested | ||
| "type" entry, indicating the data type that a standard_name should represent, and as attributes the | ||
| one ``standard_name`` element for each entry. A standard name entry consist of a ``name`` attribute |
There was a problem hiding this comment.
Can you add a sentence to this section to explain what the long name is as opposed to the description, where it is being used, please? It's entirely unclear from this paragraph that the description is for the purpose of the ESMStandardNames repo only, whereas the long_name is for the actual metadata tables only.
There was a problem hiding this comment.
@climbfuji I'm having some trouble coming up with some satisfying wording here. Right now I think the mention of "long_name" adds more confusion than it resolves. Would it make sense to just remove the reference to "long_name" all together, since with this proposed change it would no longer be a part of the Standard Names? That way we can just say the following, which I believe is clear and unambiguous:
A standard name entry consist of a
nameattribute that represents the variable name, and (optionally) adescriptionattribute that gives a detailed description of what that name represents. Note that thedescriptionfield is only provided for information and disambiguation only (though it should be unique), and does not need to be included for individual implementations of the standard names.
If you have other suggestions (general or specific) I welcome them.
There was a problem hiding this comment.
I would describe what the "description" field is about and say that the description field is not to be confused with the long_name field that is used in the actual metadata in the CCPP physics implementation in models, and then refer the reader to the CCPP technical documentation for details?
There was a problem hiding this comment.
I didn't really review this one, since you created it from the XML I assume.
nusbaume
left a comment
nusbaume
left a comment
There was a problem hiding this comment.
Thanks for another good set of updates @mkavulich! I have some comments/suggestions, but they are all (hopefully) minor.
Co-authored-by: Jesse Nusbaumer <[email protected]>
Missed this one Co-authored-by: Jesse Nusbaumer <[email protected]>
Suggestion from Dom's review Co-authored-by: Dom Heinzeller <[email protected]>
nusbaume
left a comment
nusbaume
left a comment
There was a problem hiding this comment.
Everything looks great to me now. Thanks!
|
@climbfuji In an attempt to address your comments about pointing to CCPP docs description for |
|
@climbfuji let me know if this change is sufficient or if you'd like more details. |
## Description This PR merges The `release/v1` branch into the `main` branch. The `release/v1` branch was split off from `main` about a year ago, with the intention to make major rules and name changes to improve the consistency and maintainability of both the rules and the names, without giving major inconveniences/disruption to those currently making use of the main branch. After a year of discussion and changes, it is time to bring these changes to their final resting place in the main branch. The major breaking and/or non-back-compatible changes can be summarized as such (See the subsections below for specific details about these changes): - the physics `kind` field is removed - the `long_name` field is changed to `description` - Several changes to particular terms and components of existing names have been made After this PR is merged, a `v1.0.0` tag will be created, representing the first true "versioned" version of the ESM Standard Names. While more rule changes are likely in the future to resolve open and future issues, this should be a more stable jumping-off point to allow updates and reconciliation with the names in the CCPP physics repository, which has not been resolved in many years now. For those who have not been following along with the discussion and changes related to the **v1** branch, here is a summary of each of the changes made on this branch: ### #85 First rules update, fixing misspelled standard names This first change introduced some changes to the Rules document based on discussion in the CCPP framework regular meetings. These rules changes can be summarized as follows - Introduced a more rigorous and standardized formula for constructing new standard names, with specific rules and definitions of each component of the name, attempting to cover all possible cases - Introduced the concept of "suffixes" to compliment prefixes, with mixing_ratio_wrt``_Y`` being the first example - Introduced the concept of "Reserved phrases"...for now only including "CCPP" as a reference to CCPP-specific variables In addition, a large number of misspellings within the existing names and rules were fixed. ### #87 Second rules update in v1 branch, update several name types This second change introduced the concept of "base names"; representing the main entity from which a standard name is constructed. Some existing prefixes (`surface_X` and `air_X`) were converted to suffixes (`X_at_surface` and `X_of_air`) to improve consistency with other existing names and rules, and some superfluous `surface` wording was removed from several names. The definitions for mixing ratios were improved, and the rules for constructing new names were updated and improved. ### #104 Add techincal specification, substitute abbreviations, include base name definitions This third rules change included some info about technical specifications of the standard names repository, and some formatting improvements. Instances of the term `weight` were changed to `scaling_factor` to avoid potential confusion with the physical property of weight. `long_name` descriptions were added for all the new "base names" with a few minor exceptions. Some new abbreviations were defined to help shorten names. Some unused and duplicate entries were removed. Finally, CCPP-specific variables were consolidated into their own section. ### #116 Rename long_name --> description, update description rules, expand list of abbreviations This fourth change renamed the `long_name` field to `description`, clarifying that this field should be unique, and improving/fixing some existing descriptions. Some more duplicate entries were removed. Some additional new abbreviations were defined to continue shortening names. Finally, continued defining more abbreviations to help shorten standard names further. ### #124 Remove `kind` entry, clarify rules for units and disallowed terms This fifth and final change to the v1 branch (aside from another PR to resolve intervening changes from the main branch) updated the rules to clarify disallowed terms and the role of `units`, and removed the `kind` entry. The `constants` section was organized alphabetically, and changed some names regarding `dry_air`. ## Issues Resolves - #48 - #68 - #94 - #102 Also reference already-closed issues: - #92 - #93 - #95 - #103 --------- Co-authored-by: Jesse Nusbaumer <[email protected]> Co-authored-by: Dom Heinzeller <[email protected]>
3 participants
Description
This PR attempts to address the following issues:
long_nameattribute todescription#103: renaminglong_name-->descriptionto avoid confusion with thelong_nameattribute in CCPP/CF conventions.In addition, this PR clarifies that the description field should be unique, and adds a check for this (using a re-written tools/check_xml_unique.py script with expanded functionality)
Issues
Resolves #93, #95, #103